Skip to content
Back to search

styleseed

MarketplaceWorks with Claude CodeGitHub

StyleSeed: an open-source design-method engine that aims to make expert design judgment repeatable by coding agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/bitjaru/styleseed with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/bitjaru/styleseed'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bitjaru-styleseed/badge.svg)](/listings/bitjaru-styleseed)

HTML

<a href="/listings/bitjaru-styleseed"><img src="/api/listings/bitjaru-styleseed/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The fastest path is the [single-command install](#easy-start-30-seconds) 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](docs/WINDOWS-INSTALL.md). > Reviewers can run the end-to-end [evaluator quickstart](docs/EVALUATOR-QUICKSTART.md).

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

<sub>The core workflows share resolver and verification tools. Keep the core package together; use the router to choose which workflow to invoke.</sub>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 34 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
  3. "name": "styleseed",
  4. "owner": {
  5. "name": "bitjaru",
  6. "url": "https://github.com/bitjaru"
  7. },
  8. "description": "StyleSeed: an open-source design-method engine that aims to make expert design judgment repeatable by coding agents.",
  9. "plugins": [
  10. {
  11. "name": "styleseed",
  12. "source": "./",
  13. "displayName": "StyleSeed",
  14. "description": "Open-source design-method engine aiming to make expert design judgment repeatable by coding agents, not replace experts. Compiles selected rules, preserves project choices, and records only the checks and rendered evidence that actually ran when the StyleSeed workflow is invoked.",
  15. "homepage": "https://styleseed-demo.vercel.app",
  16. "repository": "https://github.com/bitjaru/styleseed",
  17. "license": "MIT",
  18. "category": "Productivity",
  19. "keywords": [
  20. "design-system",
  21. "ui",
  22. "design-review",
  23. "tailwind",
  24. "react",
  25. "frontend",
  26. "code-quality",
  27. "accessibility",
  28. "claude-code",
  29. "cursor",
  30. "codex"
  31. ]
  32. }
  33. ]
  34. }
README.md · README · 885 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <br />
  3. # StyleSeed
  4. ### Make AI coding agents keep your design system<br />across screens, sessions, and teammates.
  5. <sub>You choose the design decisions. StyleSeed compiles them into the rules an agent reads before each screen, then checks the rendered result. <b>Support experts, not replace them with a collection of tastes.</b> Open source, for Claude Code · Codex · Cursor.</sub>
  6. <br />
  7. <br />
  8. <a href="https://styleseed-demo.vercel.app/showcase">
  9. <img src="showcase/v26-compare.png" width="720" alt="Same product, same prompt — left: default AI output, right: with StyleSeed rules locked" />
  10. </a>
  11. **Same product. Same prompt. Only the rules changed.**
  12. </div>
  13. **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 →](https://styleseed-demo.vercel.app/gate)**
  14. ## Easy Start (30 seconds)
  15. Our goal is repeatable application of expert judgment, not a claim of expert-level output today.
  16. The engine compiles selected rules, preserves project choices, and supports code and rendered
  17. checks. A score does not replace human design acceptance.
  18. [Product principles](engine/PRODUCT-PRINCIPLES.md) · [Quality-first roadmap](ROADMAP.md)
  19. **1. Open a terminal in your project folder and run this command.** Requires Node.js/npm.
  20. > **Already installed?** [Update and consolidate your existing skill list](https://styleseed-demo.vercel.app/upgrade). One request covers the same install scope, verified backup, and revision checks.
  21. ```bash
  22. npx -y skills add bitjaru/styleseed -a codex claude-code -y --copy
  23. ```
  24. Installs the core skills for **Codex and Claude Code together, with no agent, skill, or install-mode menus**.
  25. It copies the skills into this project. It does not install globally or change other projects.
  26. **2. Send one message to your agent.** Start a fresh session if the skills do not appear.
  27. - **Codex:** `$styleseed Help improve this screen. Preserve our existing design choices and show me what needs a decision.`
  28. - **Claude Code:** `/styleseed Help improve this screen. Preserve our existing design choices and show me what needs a decision.`
  29. Only `styleseed` is registered. It selects the needed internal workflow from your request.
  30. Choose unresolved design decisions together, then inspect the actual rendered result.
  31. <details>
  32. <summary>Only use one agent, or want to choose the options yourself?</summary>
  33. - Codex only: `npx -y skills add bitjaru/styleseed -a codex -y --copy`
  34. - Claude Code only: `npx -y skills add bitjaru/styleseed -a claude-code -y --copy`
  35. - Cursor or another agent: `npx skills add bitjaru/styleseed` → your agent → Project → Copy.
  36. - In the interactive list, **Codex is already included under Universal**. Do not look for it again under Additional agents.
  37. - `-y` skips installer questions; it does not bypass your coding agent's tool permissions.
  38. </details>
  39. [Claude Code guide](https://styleseed-demo.vercel.app/claude-code-ui-design) · [Codex guide](https://styleseed-demo.vercel.app/codex-ui-design) · [See examples](https://styleseed-demo.vercel.app/showcase) · [Need help?](#troubleshooting--i-applied-styleseed-but-the-ui-still-looks-bad)
  40. ### Evaluating the repository?
  41. Use the **[three-minute verification path](https://styleseed-demo.vercel.app/evaluate)** to test a
  42. clean public install before trusting the README. The source-level
  43. [evaluator quickstart](docs/EVALUATOR-QUICKSTART.md) then connects that install to the published
  44. release manifest, Windows PowerShell evidence, CI, SBOM, benchmark boundary, and production build.
  45. > **Want a first PR?** Fix a doc, add a regression fixture, improve a skin, or claim a
  46. > [`good first issue`](https://github.com/bitjaru/styleseed/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22good%20first%20issue%22).
  47. > Small docs and test fixes need no proposal. See the [15-minute contribution path](CONTRIBUTING.md#first-pr-in-about-15-minutes).
  48. For a fixed evaluation version, use the **[v5.0.0 release archive](https://github.com/bitjaru/styleseed/releases/tag/v5.0.0)** and its checksums. The default `bitjaru/styleseed` command follows mutable `main`.
  49. ### Upgrading an existing 23-skill install
  50. Reinstall through the same channel. Then ask `StyleSeed, consolidate my old skill entries`.
  51. The update workflow verifies the new unified payload and archives only unmodified old `ss-*`
  52. directories outside skill discovery; modified copies remain for review. Restart the agent session.
  53. Use `$styleseed build` / `/styleseed build` instead of the former `$ss-build` / `/ss-build`
  54. registrations. All 22 workflows remain bundled; selecting only `styleseed` is now sufficient.
  55. ## What the current rules check
  56. StyleSeed ships **74 craft rules** and a **0–100 scored gate** that tells an installed agent to
  57. revise screens below 80 before presentation. Checks must be interpreted through the selected
  58. grammar and project contract, not as universal taste. The workflow must actually be invoked;
  59. a markdown file alone cannot block delivery, and 80 points is not expert approval.
  60. | Check | Why |
  61. |---|---|
  62. | Unselected default accent | require an intentional, recorded color role |
  63. | Emoji as UI icons 🚗 🧺 ⭐ | inject random colors, render differently per OS |
  64. | The icon-in-a-chip above every feature card | gen-1 AI tell — decoration pretending to be information |
  65. | Same-weight cards that hide the current priority | the #1 machine-composed tell; truly equivalent options may share weight |
  66. | Accidental flat-black backgrounds | use the selected grammar's surface model; explicit supported exceptions differ |
  67. | Type sizes outside the selected scale | prevent unintentional hierarchy drift |
  68. | Hardcoded hex in components | tokens only — otherwise the lock can't hold across screens |
  69. <sub>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 ↓](#what-happens-after-easy-start)</sub>
  70. <div align="center">
  71. <br />
  72. <a href="https://styleseed-demo.vercel.app">
  73. <img src="showcase/demo.gif" width="560" alt="Same chat UI morphing across Toss, Raycast, and Arc brand skins" />
  74. </a>
  75. **One component. Three token skins.** Same chat UI morphing across Toss · Raycast · Arc-inspired
  76. token sets. A skin changes color and type material; a StyleSeed brand recipe changes the actual
  77. geometry, containment, controls, collections, density, and motion.
  78. <sub>Skins are *inspired-by* token sets, not recreations. [Compare the nine structural recipes →](https://styleseed-demo.vercel.app/recipes)</sub>
  79. <br />
  80. [![▶ Live Demo](https://img.shields.io/badge/▶_Live_Demo-Open-111111?style=for-the-badge&logoColor=white)](https://styleseed-demo.vercel.app)
  81. &nbsp;
  82. [![▶ Motion Gallery](https://img.shields.io/badge/▶_Motion_Gallery-Live-8B5CF6?style=for-the-badge&logoColor=white)](https://styleseed-demo.vercel.app/motion)
  83. ![74 design rules](https://badgen.net/badge/rules/74/8B5CF6)
  84. ![1 skill](https://badgen.net/badge/skills/1/6C5CE7)
  85. ![8 output grammars](https://badgen.net/badge/grammars/8/2563EB)
  86. ![5 adapters](https://badgen.net/badge/adapters/5/0F766E)
  87. ![9 brand recipes](https://badgen.net/badge/recipes/9/DB2777)
  88. ![8 palette recipes](https://badgen.net/badge/palettes/8/D56A45)
  89. ![7 brand skins](https://badgen.net/badge/skins/7/6C5CE7)
  90. [![GitHub stars](https://badgen.net/github/stars/bitjaru/styleseed)](https://github.com/bitjaru/styleseed/stargazers)
  91. [![License](https://badgen.net/github/license/bitjaru/styleseed)](https://github.com/bitjaru/styleseed/blob/main/LICENSE)
  92. [![Mentioned in Awesome AI Tools for UI](https://awesome.re/mentioned-badge.svg)](https://github.com/maxbogo/awesome-ai-tools-for-ui)
  93. <br />
  94. **Expert decisions become repeatable instructions — not one universal aesthetic.**
  95. **Judgment with implementation context** — decisions, applicability, and evidence, not just palettes &nbsp;·&nbsp;
  96. **Right grammar for the result** — consumer service, operations, technical, editorial,
  97. commerce, institutional, marketing, or sequential story &nbsp;·&nbsp;
  98. **Real morphology choices** — nine brand recipes change structure and component selection,
  99. not just palette &nbsp;·&nbsp;
  100. **Generative palette engine** — any key color becomes OKLCH ramps, context-fit surfaces,
  101. a scored companion, semantic roles, contrast evidence, CSS tokens, and media anchors; eight
  102. recipes remain maintained product postures &nbsp;·&nbsp;
  103. **Studio pipeline** — three directions, human selection, interaction scenes, image/video jobs,
  104. working prototype, and a prototype-first reel &nbsp;·&nbsp;
  105. **References become rules** — `/styleseed reference` compiles screenshots, URLs, Figma, or an existing
  106. UI into an evidence-backed project grammar &nbsp;·&nbsp;
  107. **Only the context you need** — `/styleseed resolve` compiles the chosen method into a small,
  108. hash-verifiable project bundle &nbsp;·&nbsp;
  109. **Beyond web UI** — adapters for product UI, social carousels, decks, documents, and graphics &nbsp;·&nbsp;
  110. **Fights the AI tells** — the default indigo, the icon-chip cliché, template layouts, rainbow lists &nbsp;·&nbsp;
  111. **Auxiliary proof gates** — code score + rendered pixel verification before you see it &nbsp;·&nbsp;
  112. **Every agent** — ships `CLAUDE.md` + `AGENTS.md` + `.cursorrules` &nbsp;·&nbsp;
  113. **A design lock that stops drift** &nbsp;·&nbsp;
  114. **Free & MIT**
  115. <br />
  116. <a href="engine/ARCHITECTURE.md">
  117. <img src="assets/styleseed-architecture.svg" width="900" alt="StyleSeed engine architecture: intent and references become output grammars, combine with surface adapters and bounded project choices, then pass code and pixel gates" />
  118. </a>
  119. <sub>Core judgment × output grammar × surface adapter × domain/page × brand recipe × palette recipe × optional profile. [Read the architecture →](engine/ARCHITECTURE.md)</sub>
  120. <br /><br />
  121. <img src="showcase/v26-compare.png" width="840" alt="Same product, same prompt — only the rules changed. Hero: default indigo gradient text, sparkle badge and a placeholder mock vs a chosen emerald accent with the real product panel as the focal point. How-it-works: three identical icon-chip cards vs a hairline-joined numbered flow that reads designed." />
  122. <sub>Full pages: [before](showcase/v26-before.png) · [after](showcase/v26-after.png) · **[more before/afters →](https://styleseed-demo.vercel.app/why)**</sub>
  123. <sub>🔥 We ran an early version of *this page* through our own gate. **[It scored 58/100 → here's the receipt](https://styleseed-demo.vercel.app/scorecard)**</sub>
  124. <br /><br />
  125. <img src="showcase/style-gallery.png" width="840" alt="The same Relay product rendered in six StyleSeed presets — swiss (sharp grid, red), editorial (serif seasoning, oxblood), technical (dark, dense, teal), warm-dtc (pill, terracotta), minimal-mono (whitespace, one accent), brutalist-lite (hard borders, cobalt). Each is coherent and distinct, none looks generic." />
  126. <sub>Same product, six looks — each one `/styleseed restyle <preset>` away. Coherent, distinct, never generic.</sub>
  127. <br />
  128. [Easy Start](#easy-start-30-seconds) · [Studio](https://styleseed-demo.vercel.app/studio) · [Palettes](https://styleseed-demo.vercel.app/palettes) · [Claude Code UI guide](https://styleseed-demo.vercel.app/claude-code-ui-design) · [Codex UI guide](https://styleseed-demo.vercel.app/codex-ui-design) · [Brand recipes](https://styleseed-demo.vercel.app/recipes) · [Architecture](engine/ARCHITECTURE.md) · [Engine + Recipes + Skins](#how-it-works-engine--recipes--skins) · [Motion](#named-motion-system) · [Skills](#one-skill-22-internal-workflows) · [Wiki](../../wiki) · [한국어](README-KR.md)
  129. <br />
  130. </div>
  131. ---
  132. ## What happens after Easy Start
  133. **Why the prompt installs first:** the context compiler and quality gates can only *run* when the
  134. skills are installed. Installing turns `STYLESEED.md` into a small source-hashed rule bundle,
  135. then actually scores and fixes the result before you see it. Without installation,
  136. [`llms.txt`](https://styleseed-demo.vercel.app/llms.txt) still tells any agent how StyleSeed is
  137. structured and where its machine-readable catalog lives, but compilation and gates become a
  138. weaker manual path. Works with **Claude Code (`CLAUDE.md`), Codex / Amp / Gemini CLI
  139. (`AGENTS.md`), and Cursor (`.cursorrules`)** — StyleSeed ships all three. (Planning first is what
  140. keeps the result from looking random — see [Troubleshooting](#troubleshooting--i-applied-styleseed-but-the-ui-still-looks-bad).)
  141. **What your agent actually does with StyleSeed loaded:**
  142. ```text
  143. you ▸ build me a billing settings page
  144. agent ▸ (plan mode) key color? for billing I'd go deep teal — #0F766E, mood: sharp · calm ·
  145. trustworthy (not the default indigo). Motion: Snap. ok? ▸ y
  146. agent ▸ ✓ wrote STYLESEED.md — skin, accent, font, radius, motion locked for project-scoped visual work
  147. agent ▸ building… running the quality gate before I show you anything
  148. gate ▸ ✗ two accent colors ✗ "normal" rows colored ✗ no empty state → fixing
  149. agent ▸ ✓ 88/100 — one accent, grey normal states, real empty/error states. here's the page.
  150. ```
  151. **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](#already-built-something-generic-retrofit-it) too.
  152. > **The method stays open and portable.** The sources are plain markdown; installation adds the
  153. > deterministic context compiler, manifest, and executable gates. If installation is unavailable,
  154. > [`llms.txt`](https://styleseed-demo.vercel.app/llms.txt) gives any agent the portable routing
  155. > contract, but it cannot provide the same reproducible local compile by itself.
  156. **Want the single StyleSeed skill too** (the `styleseed` router plus 22 `ss-*` workflows for Studio, context resolution, setup, build, review, score, and verification)?
  157. ```bash
  158. npx -y skills add bitjaru/styleseed -a codex claude-code -y --copy
  159. ```
  160. Installs one self-contained StyleSeed skill into Codex and Claude Code in this project.
  161. For other agents, use the interactive command in Easy Start. Then run
  162. `/styleseed setup` → `/styleseed resolve` in Claude Code or `$styleseed setup` → `$styleseed resolve` in Codex (you can
  163. also choose StyleSeed from Codex's `/skills` picker). The resolver writes a targeted
  164. `.styleseed/effective-rules.md` bundle plus a source-hash manifest, so the agent does not need
  165. the 220KB full handbook for every task. Your agent may ask you to approve tools on first use.
  166. No install possible? Read [`llms.txt`](https://styleseed-demo.vercel.app/llms.txt) for the
  167. portable routing contract.
  168. <details>
  169. <summary>Claude Code plugin marketplace</summary>
  170. `npx skills add` copies the skills into your project and works across every supported agent, so it
  171. stays the recommended path. If you would rather have Claude Code manage StyleSeed as a versioned
  172. plugin it can update in place, this repository is also a marketplace:
  173. ```bash
  174. claude plugin marketplace add bitjaru/styleseed
  175. claude plugin install styleseed@styleseed
  176. ```
  177. Both paths install the same public skill with 22 internal workflows. The optional `ss-learn` extension is in neither.
  178. </details>
  179. **Your agent, its exact path:**
  180. | Your agent | Reads | Fastest install |
  181. |---|---|---|
  182. | **Claude Code** | `CLAUDE.md` + `/styleseed` | `npx -y skills add bitjaru/styleseed -a claude-code -y --copy` |
  183. | **Cursor** | `.cursorrules` | `cp engine/.cursorrules .cursorrules` — or paste the prompt above |
  184. | **Codex** | `AGENTS.md` + `$styleseed` (`.agents/skills`) | `npx -y skills add bitjaru/styleseed -a codex -y --copy` |
  185. | **Amp · Gemini CLI** | `AGENTS.md` + skills | `npx skills add bitjaru/styleseed` |
  186. | **Windsurf · Copilot · any other** | supported agent skills, or portable guidance | use the interactive installer; reading `llms.txt` alone does not execute local checks |
  187. <sub>More paths (manual copy, Cursor, awesome-design-md brands) in [Install by hand](#install-by-hand) below.</sub>
  188. ---
  189. ## Who is this for?
  190. - You asked **Claude Code** or **Cursor** to build a dashboard and it came out amateur-looking
  191. - You're **vibe coding** a SaaS app with no design system yet, so every new screen comes out different
  192. - You use **shadcn/ui** but the output still feels generic
  193. - You want Toss-like consumer refinement **only where that grammar fits**, not on every output
  194. - You make social carousels, decks, reports, covers, or other vibe-coded visual artifacts
  195. - You have references and want their repeatable design language extracted instead of cloned
  196. - You're building a **Claude Code skill** or **Cursor rules** setup for design
  197. - You ship fast with AI and need professional UI that doesn't look AI-generated
  198. Spacing feels wrong? [Inspect the live 64px → 12px CSS inheritance repair](https://styleseed-demo.vercel.app/fix-ui-spacing), then try the prompt on your own screen. This is a synthetic regression example, not a customer outcome or an optimal-spacing claim.
  199. ## Where StyleSeed fits among design-AI skills
  200. Design skills for coding agents are a crowded field now. Hallmark, Impeccable and Taste Skill make a
  201. new screen look designed; Impeccable also keeps a `DESIGN.md` and checks code against its tokens.
  202. StyleSeed works on what happens after the first screen: keeping one product consistent across
  203. screens, sessions and teammates.
  204. | | **StyleSeed** | Design skills (Hallmark, Impeccable, Taste) | `DESIGN.md` collections | UI generators (Claude Design, v0…) |
  205. |---|---|---|---|---|
  206. | Keeping decisions across sessions | a rule bundle compiled per screen from a settings file; same settings give the same bundle, hash-checked | Impeccable: `DESIGN.md` plus a detector; Hallmark: optional `design.md` lock | the agent re-reads the file | ❌ |
  207. | What is stored | decisions (domain, page type, grammar, palette posture) and the per-screen rules built from them | token values and prose | token values | ❌ |
  208. | Palette | computed from one key colour in OKLCH, contrast-corrected, deterministic | chosen by the agent or from a theme catalogue | listed | the model's choice |
  209. | Checks | 6 deterministic source checks, rendered measurement at 1440 and 390, an 8-category rubric score | Impeccable: 62 deterministic rules and an edit hook; Hallmark and Taste: browser lint | ❌ | ❌ |
  210. | Where the rules come from | the maintainer's stated reasons: every catalog rule is at evidence level `inferred`. [`research/cases`](research/cases/README.md) collects public sources, evidence levels and counterexamples; no rule cites a case yet | the author's experience; Taste: a 247-site study | scraped brands | ❌ |
  211. | Best at | many screens of one product | one striking new page (Hallmark, Taste); refining an existing screen (Impeccable) | the brand look | a first draft |
  212. They combine. A `DESIGN.md` or a generator's first draft can feed StyleSeed's rules, and where
  213. another skill already does a job well, StyleSeed does not claim it. Checked against each project's
  214. README on 2026-11-02.
  215. ## What it actually enforces (a taste)
  216. The engine records decisions with their task, allowed variation, and verification needs:
  217. - **Attention follows the task** — a personal summary may lead with one value; monitoring may use equally weighted comparison panels.
  218. - **Color has stable roles** — action, status, category, brand, and content can use different hues while remaining distinguishable without color alone.
  219. - **Type preserves meaning** — a large balance with a smaller unit is one option; tabular values, prose, and approved script-specific scales need other relationships.
  220. - **Geometry follows component roles** — containers, controls, focus outlines, and avatars can differ coherently within one system.
  221. - **Separation fits the context** — whitespace, tone, borders, and shadows may work separately or together; there is no mandatory shadow recipe.
  222. - **Equivalent information repeats** — use consistent rows and comparison panels; vary when priority, data question, or narrative role changes.
  223. - **Content supplies specificity** — use real product evidence, actual data series, and relevant media with intentional crops and fallbacks.
  224. - **Access and function remain binding** — preserve contrast, labels, focus, operable targets, meaningful states, and a complete reduced-motion result.
  225. Defaults guide a project without an established system; they do not replace approved choices.
  226. [Research scope, counterexamples, and the 18 corrections →](research/design-patterns-2026-10-13/README.md)
  227. [See all 74 rules →](engine/DESIGN-LANGUAGE.md) · [the craft & coherence laws →](engine/VISUAL-CRAFT.md)
  228. ## Data vs Judgment
  229. Tokens and components are necessary, but they do not explain every design decision. Agents also
  230. need to know when a pattern applies, why it fits the task, which choices are approved, and how
  231. to handle exceptions. Expert judgment and implementation material need to travel together.
  232. StyleSeed's goal is to make that judgment repeatable while leaving intent, tradeoffs, and
  233. acceptance with people. The current engine is a starting point; component-context experiments
  234. and independent human evaluation are the next steps, not completed capabilities.
  235. <div align="center">
  236. <a href="https://styleseed-demo.vercel.app/how-it-thinks">
  237. <img src="assets/coherence-mixed-vs-unified.svg" width="840" alt="Two consumer-summary cards illustrate one way to coordinate action colors, type, and container shapes. Other role systems can use multiple colors and radii." />
  238. </a>
  239. </div>
  240. <br />
  241. **[See the before/after →](https://styleseed-demo.vercel.app/why)** — the same dashboard brief, generated generically vs. with the 74 rules applied. Every fix annotated with the rule behind it.
  242. StyleSeed is a **design-method engine** — 74 craft rules, 8 output grammars, 5 surface
  243. adapters, 48 components, a reference compiler, a named motion system, and one agent skill with 22 internal workflows:
  244. ```
  245. "Use the approved semantic roles rather than inventing component-local colors."
  246. "Select grouping and density for the task, not for a favorite template."
  247. "Preserve the project's type and surface system across screens."
  248. "Loading, empty, error, and recovery states are part of the implementation."
  249. "Record unsupported choices instead of silently changing the design system."
  250. ```
  251. StyleSeed organizes maintained guidance by grammar, adapter, domain, and project choices,
  252. then compiles the selected context for the agent. Defaults are not universal expert decisions:
  253. unsupported project choices need an explicit review, not a silent palette or component swap.
  254. <div align="center">
  255. <img src="showcase/light-hero.png" width="260" alt="Light mode" />&nbsp;&nbsp;&nbsp;&nbsp;<img src="showcase/dark-hero.png" width="260" alt="Dark mode" />
  256. <br />
  257. <em>Same engine, different token skins. Examples, not proof that expert review is unnecessary.</em>
  258. </div>
  259. <details>
  260. <summary><strong>See full page</strong></summary>
  261. <div align="center">
  262. <img src="showcase/light-full.png" width="260" alt="Light full" />&nbsp;&nbsp;&nbsp;&nbsp;<img src="showcase/dark-full.png" width="260" alt="Dark full" />
  263. </div>
  264. </details>
  265. ## Works with Claude Design
  266. [Claude Design](https://claude.ai/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*.
  267. **StyleSeed + Claude Design together:**
  268. 1. Claude Design generates the layout and components (fast scaffolding)
  269. 2. StyleSeed's 74 rules refine the output (design judgment layer)
  270. 3. Brand skins make it look like your brand, not like "AI made this"
  271. Drop `DESIGN-LANGUAGE.md` into your Claude Design workflow and the same model produces noticeably more refined output — without changing a single prompt.
  272. ### "Why not just use the official `frontend-design` skill?"
  273. Use both — they solve different halves of the problem. Anthropic's official [`frontend-design`](https://github.com/anthropics/skills) skill scaffolds a clean screen fast, and it's a great starting point. StyleSeed is the layer **on top**:
  274. | | Official `frontend-design` | **StyleSeed** |
  275. | --- | --- | --- |
  276. | Gets you a coherent screen | ✅ | ✅ |
  277. | Names & bans the generic-AI tells | — | ✅ by name (default indigo, icon-chip, rainbow lists…) |
  278. | Scored gate that fixes before you see it | — | ✅ `/styleseed score` loops to ≥80 |
  279. | Locks decisions so they don't drift across prompts | — | ✅ `STYLESEED.md` |
  280. | Presets + dials to move the whole look at once | — | ✅ `/styleseed restyle`, `/styleseed dial` |
  281. Official gets you *coherent*. StyleSeed keeps you from looking *templated*. Run the official skill to scaffold, then let StyleSeed's gate refine and enforce.
  282. ## Install by hand
  283. The fastest path is the [single-command install](#easy-start-30-seconds) above. To wire StyleSeed into an existing project manually, use one of the options below.
  284. > **New to this? Read top to bottom — every step matters.** The most common
  285. > mistake is expecting setup to work before the skill is installed. Claude
  286. > Code scans `.claude/skills/`; Codex scans `.agents/skills/`.
  287. > Windows users can follow the copy-pasteable [PowerShell verification path](docs/WINDOWS-INSTALL.md).
  288. > Reviewers can run the end-to-end [evaluator quickstart](docs/EVALUATOR-QUICKSTART.md).
  289. ### Option 1: Interactive Setup (Recommended)
  290. **Step 1 — Install the skills.** For Codex and Claude Code together:
  291. ```bash
  292. npx -y skills add bitjaru/styleseed -a codex claude-code -y --copy
  293. ```
  294. For a manual project-local install, clone StyleSeed and copy the canonical
  295. skill folders into the path your agent scans:
  296. ```bash
  297. git clone https://github.com/bitjaru/styleseed.git /tmp/styleseed
  298. # Claude Code
  299. mkdir -p .claude/skills
  300. cp -r /tmp/styleseed/engine/.claude/skills/* .claude/skills/
  301. # Codex (repository-scoped skills)
  302. mkdir -p .agents/skills
  303. cp -r /tmp/styleseed/engine/.claude/skills/* .agents/skills/
  304. ```
  305. **Step 2 — Start a fresh agent session**, open your project, and invoke setup:
  306. ```text
  307. Claude Code: /styleseed setup
  308. Codex: $styleseed setup # or open /skills and choose styleseed
  309. ```
  310. The wizard then walks you through:
  311. 1. Product job, surface, and output grammar
  312. 2. One of nine brand recipes for morphology (`enterprise-workbench`, `public-service`, etc.)
  313. 3. Brand color or a custom/built-in token skin
  314. 4. Font, density, motion, and one signature move
  315. 5. A compiled rule bundle, first build, score, and rendered verification
  316. > Don't see the skills? For Claude Code, check `.claude/skills/` and use the
  317. > `/styleseed` command. For Codex, check `.agents/skills/`, open `/skills`, or invoke
  318. > `$styleseed setup`. Start a new session after installing if discovery looks stale.
  319. ### Option 2: Manual Setup
  320. 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):
  321. ```bash
  322. # Design reference + AI guide
  323. mkdir -p .claude
  324. cp /tmp/styleseed/engine/DESIGN-LANGUAGE.md .claude/DESIGN-LANGUAGE.md
  325. cp /tmp/styleseed/engine/CLAUDE.md ./CLAUDE.md
  326. # Styles and components
  327. mkdir -p src/styles src/components
  328. cp -r /tmp/styleseed/engine/css/* src/styles/
  329. cp -r /tmp/styleseed/engine/components/* src/components/
  330. # Pick a skin — copy its theme.css alongside the other css files
  331. cp /tmp/styleseed/skins/stripe/theme.css src/styles/theme.css
  332. ```
  333. ### Option 3: Just give AI the URL
  334. ```
  335. Refer to https://github.com/bitjaru/styleseed — read engine/CLAUDE.md
  336. and engine/DESIGN-LANGUAGE.md, then build a SaaS dashboard.
  337. Use skins/stripe/theme.css for the color palette.
  338. ```
  339. ### Option 4: Cursor
  340. ```bash
  341. cp engine/.cursorrules your-project/.cursorrules
  342. ```
  343. <sub>The core workflows share resolver and verification tools. Keep the core package together; use the router to choose which workflow to invoke.</sub>
  344. ## Troubleshooting — "I applied StyleSeed but the UI still looks bad"
  345. For installation, configuration, or stale-evidence problems, first run the [read-only project
  346. doctor](docs/PROJECT-DOCTOR.md). It separates a healthy installation and current compiled rules
  347. from missing or invalid evidence; it does not claim that a screen looks good.
  348. The honest reason: **consistency comes from constraints.** If you used a bare *"apply StyleSeed"*
  349. prompt (without the plan-mode + key-color + quality-gate steps [the prompt above](#easy-start-30-seconds)
  350. includes), the agent reads a summary once and improvises — so colors land at random and there's
  351. no key color. The reference demo ([styleseed-demo.vercel.app](https://styleseed-demo.vercel.app))
  352. came out polished because it was built with the full rules in context and iterated with
  353. `/styleseed review` — not one-shot. Recreate those conditions:
  354. 1. **Plan first.** In Claude Code press <kbd>Shift</kbd>+<kbd>Tab</kbd> 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.
  355. 2. **Select the output grammar, adapter, and primary action color.** Additional hues need stable
  356. semantic, categorical, editorial, or brand roles. No role = random color drift.
  357. 3. **Compile only the selected rules:** run `/styleseed resolve` or `$styleseed resolve`, then make the agent
  358. read `.styleseed/effective-rules.md`. The manifest pins selections and hashes. Use
  359. `llms-full.txt` only to debug an unresolved source ambiguity.
  360. 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.
  361. 5. **Be specific:** *"Build a dashboard in the Linear skin, one blue accent, Snap motion, following StyleSeed's rules"* beats *"build a dashboard."*
  362. 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."*
  363. > **More constraints = less variance.** Plan mode + a pinned key color + installed rules + a review pass is the difference between "looks generated" and "looks designed."
  364. ## Already built something generic? Retrofit it
  365. StyleSeed isn't only for new screens — it's **the design counterpart to a code review** for UI you
  366. already shipped. If an earlier build looks *coherent but generic* (an unchosen default indigo, body
  367. text that is hard to read at its real viewport, the same Lucide-icon-in-a-pale-chip on every card,
  368. equal emphasis that hides what matters now):
  369. 1. **`/styleseed score src/…`** — grades the screen 0–100 and names the exact "AI-made" tells (unchosen
  370. default accent, icon-chip cliché, body type outside the approved scale or unreadable at its real
  371. viewport, missing task-appropriate attention, missing states).
  372. 2. **`/styleseed review src/…`** — the design code-review. It is read-only: it cites the selected
  373. contract for each problem and recommends fixes (retint to your key color, drop the chips, correct
  374. the type roles, restore the current priority). Ask the agent to apply them, then re-score to **≥80**.
  375. 3. **`/styleseed update` → Retrofit** — no design lock yet? It writes a `STYLESEED.md` (mood, key color,
  376. font, surface) so the whole project stops drifting, then upgrades screen by screen.
  377. The rules got stronger in [v2.5.0](https://github.com/bitjaru/styleseed/releases/tag/v2.5.0), so a
  378. screen that passed the old bar may score lower now — that's the point. Fixing it is what makes it
  379. stop looking AI-made.
  380. ## How It Works: Engine + Recipes + Skins
  381. ```
  382. ┌─────────────────────────────────────────────────┐
  383. │ StyleSeed Engine (brand-agnostic) │
  384. │ │
  385. │ 74 rules · 8 grammars · 5 adapters · 1 skill │
  386. │ Layout · Composition · Typography · UX · A11y │
  387. └──────────────────────┬──────────────────────────┘
  388. │
  389. Pick a recipe ↓
  390. │
  391. calm · native · enterprise · developer · commerce
  392. public service · creative · editorial · expressive
  393. │
  394. Apply a skin ↓
  395. │
  396. ┌──────┬──────┬──────┬──────┬──────┬─────────┐
  397. │ Toss │Stripe│Linear│Vercel│Notion│ 58 more │
  398. │ │ │ │ │ │(awesome)│
  399. └──────┴──────┴──────┴──────┴──────┴─────────┘
  400. ```
  401. **Engine** = how the artifact is judged (design intelligence)
  402. - 74 visual design rules (layout, composition, rhythm, forbidden patterns)
  403. - 48 React components (32 primitives + 16 patterns)
  404. - A named motion system (5 seeds + a copy-paste keyword library)
  405. - 22 internal workflows (Studio, context compiler, reference compiler, setup, UI, motion, UX, and accessibility; learning is a separate extension)
  406. - 8 maintained semantic palette recipes, with validated project overrides
  407. **Brand recipe** = how the artifact is shaped (morphology)
  408. - 9 maintained choices in [`BRAND-RECIPES.md`](engine/BRAND-RECIPES.md)
  409. - Changes containment, radius/border/elevation, navigation, controls, collections, density,
  410. responsive behavior, and motion
  411. - Carries source lineage without official logos, assets, fonts, copy, or trademarked arrangements
  412. **Palette recipe** = how color roles relate (semantic hierarchy)
  413. - 8 maintained choices in [`PALETTE-RECIPES.md`](engine/PALETTE-RECIPES.md)
  414. - Binds canvas, surface, navigation chrome, text, action, status, focus, and generated-media anchors
  415. - Every required text/action/focus pair passes deterministic contrast validation
  416. **Skin** = semantic color and type material (visual identity)
  417. - Just a `theme.css` file with color variables
  418. - 7 built-in skins: Toss, Stripe, Linear, Notion, Raycast, Arc, Vercel
  419. - 58+ more available from [awesome-design-md](https://github.com/VoltAgent/awesome-design-md)
  420. - Or create your own (change `--brand` and you're done)
  421. **Data repos** ([awesome-design-md](https://github.com/VoltAgent/awesome-design-md)) = paint colors.
  422. **StyleSeed** = the rulebook for where to put the paint. Use them together: they provide the skin,
  423. StyleSeed provides the brain. (Full comparison in [Where StyleSeed fits](#where-styleseed-fits-among-design-ai-skills).)
  424. ## Named Motion System
  425. <div align="center">
  426. <a href="https://styleseed-demo.vercel.app/motion">
  427. <img src="showcase/motion-gallery.gif" width="720" alt="StyleSeed motion gallery — flashy named moves: tilt-3d, magnetic, glow-pulse, gradient-sweep, blob-morph, spotlight" />
  428. </a>
  429. <br />
  430. <em>Flashy, named, copy-paste moves — live at <a href="https://styleseed-demo.vercel.app/motion">/motion</a></em>
  431. </div>
  432. <br />
  433. StyleSeed gives motion a **vocabulary** for projects that need it. Preserve approved motion roles first; a named recipe, a fade, an instant state change, or a static page can each fit the task. The optional library has two layers:
  434. **1. Seeds = personality.** Five named presets, each a spreadable framer-motion recipe in five contexts (`entrance` / `exit` / `hover` / `press` / `layout`):
  435. | Seed | Vibe | Inspiration |
  436. |------|------|-------------|
  437. | **Spring** | bouncy, energetic, playful | Arc, Toss |
  438. | **Silk** | smooth, elegant, continuous | Stripe, Linear |
  439. | **Snap** | instant, decisive, precise | Raycast, Linear |
  440. | **Float** | weightless, gentle, dreamy | Apple |
  441. | **Pulse** | rhythmic, alive, punchy | Discord, music apps |
  442. ```tsx
  443. import { spring } from "@engine/motion";
  444. <motion.button {...spring.hover} {...spring.press}>Save</motion.button>
  445. ```
  446. **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.
  447. ▶ **[Preview & copy every motion at the live gallery →](https://styleseed-demo.vercel.app/motion)**
  448. &nbsp;·&nbsp; [Vibe-code your own → the motion guide](https://styleseed-demo.vercel.app/motion/guide)
  449. **Motion is scoped by the task and surface.** Choose it for feedback, orientation, or an approved narrative purpose:
  450. | Surface | Motion posture |
  451. |---|---|
  452. | **App / dashboard / data / forms** | Keep reading and interaction responsive. Motion may explain state or provide feedback; it must not delay essential values or obscure comparisons. |
  453. | **Marketing / landing / brand pages** | A static page is valid. When the narrative benefits, optional scroll-linked reveals, sticky sequences, parallax, or richer media may support it. |
  454. Preserve native scroll control, immediate access to content and actions, and a complete reduced-motion result. Prefer compositor-friendly animation where suitable, and measure performance and behavior on the target devices. Motion is optional; a preset name or animation count is not a quality test. <sub>(Rules: DESIGN-LANGUAGE §43 · PAGE-TYPES → Landing)</sub>
  455. 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.
  456. ## Available Skins
  457. | Skin | Style | Source |
  458. |------|-------|--------|
  459. | **[toss](skins/toss/)** | Korean fintech — purple, minimal, data-focused | Original |
  460. | **[stripe](skins/stripe/)** | Professional — indigo, clean, multi-layer shadows | awesome-design-md |
  461. | **[linear](skins/linear/)** | Dark-first — violet, minimal, developer-focused | awesome-design-md |
  462. | **[vercel](skins/vercel/)** | Monochrome — black & white, geometric | awesome-design-md |
  463. | **[notion](skins/notion/)** | Warm — blue accent, friendly, warm neutrals | awesome-design-md |
  464. | **[raycast](skins/raycast/)** | Dark, punchy — red accent, snappy, launcher energy | awesome-design-md |
  465. | **[arc](skins/arc/)** | Playful — bold gradients, rounded, expressive | awesome-design-md |
  466. | **58+ more** | Any brand from [awesome-design-md](https://github.com/VoltAgent/awesome-design-md) | Auto-fetched via `/styleseed setup` — nothing vendored |
  467. ## Engine Contents
  468. ```
  469. engine/
  470. ├── CLAUDE.md # AI reads this automatically
  471. ├── AGENTS.md # Codex and other AGENTS.md-compatible agents
  472. ├── DESIGN-LANGUAGE.md # 74 visual design rules (brand-agnostic)
  473. ├── .claude/skills/styleseed/ # One registered skill
  474. │ ├── SKILL.md # Route the user's request
  475. │ └── workflows/ # 22 internal workflows, each with WORKFLOW.md
  476. │ ├── ss-resolve/ # Compiler and runtime
  477. │ ├── ss-build/ # Build loop
  478. │ ├── ss-verify/ # Rendered evidence
  479. │ └── … # Setup, tokens, review, motion, update, etc.
  480. ├── motion/ # 5 motion seeds + keyword library
  481. ├── components/
  482. │ ├── ui/ # 32 primitives (shadcn/ui + motion)
  483. │ └── patterns/ # 16 dashboard patterns
  484. ├── css/ # base.css, fonts.css, index.css
  485. ├── tokens/ # 6 JSON token files
  486. ├── utils/ # Formatting utilities
  487. ├── icons/ # Custom SVG icon library
  488. └── scaffold/ # Vite 6 + React 18 starter
  489. ```
  490. ## One Skill, 22 Internal Workflows
  491. ### Setup
  492. | Skill | What It Does |
  493. |-------|-------------|
  494. | `/styleseed` | **Route a general request** — resolve the current artifact and choose exactly one first StyleSeed workflow |
  495. | `/styleseed studio` | **Run creative direction end to end** — role-based references → three directions → human selection → interaction/media plans → working prototype → temporal and visual evidence |
  496. | `/styleseed resolve` | **Compile only the active context** — lock → grammar + adapter + domain/page + brand recipe + profile + craft baseline → small bundle + source-hash manifest |
  497. | `/styleseed build` | **The whole loop, enforced** — lock the look → build → score → fix to ≥80 → *then* show. Use this instead of building UI free-hand |
  498. | `/styleseed reference` | **Compile references into a project grammar** — evidence, confidence, semantic tokens, anti-patterns, and a transfer validation artifact |
  499. | `/styleseed dial` | Turn one axis up/down deterministically — `density denser`, `radius sharper`, `color more-muted`, `weight bolder`. Moves many tokens together, keeps the guardrails, re-gates |
  500. | `/styleseed restyle` | Re-style to a named aesthetic — `swiss` · `editorial` · `technical` · `warm-dtc` · `minimal-mono` · `brutalist-lite`. A coherent coordinate, not a stacked filter |
  501. | `/styleseed setup` | **Interactive wizard** — select output grammar + adapter + brand recipe, then bounded brand/profile values |
  502. ### UI — Build It Right
  503. | Skill | What It Does |
  504. |-------|-------------|
  505. | `/styleseed component` | Generate components following design conventions |
  506. | `/styleseed page` | Scaffold pages with proper layout structure |
  507. | `/styleseed pattern` | Compose UI patterns (card grid, chart, list) |
  508. | `/styleseed motion` | Apply a named motion — a seed or a keyword move (`toggle-flip`, `tilt-3d`...) |
  509. | `/styleseed review` | Audit code for design system violations |
  510. | `/styleseed tokens` | View, add, or modify design tokens |
  511. | `/styleseed a11y` | Accessibility audit (WCAG 2.2 AA) |
  512. | `/styleseed lint` | Quick automated lint — catches common violations in seconds |
  513. | `/styleseed score` | Score UI quality 0-100 with a category breakdown + prioritized fix list (reads the code) |
  514. | `/styleseed verify` | **The visual gate** — render the screen, screenshot it, score what you *see* (dead whitespace, unloaded fonts, a priority that is hard to find, blank empty states), fix + re-render in a build or fix task |
  515. | `/styleseed update` | Pull latest engine updates — analyzes your project and updates safely |
  516. ### UX — Flows, audits, and copy with the reasoning written down
  517. | Skill | What It Does |
  518. |-------|-------------|
  519. | `/styleseed flow` | Design user flows (progressive disclosure, information pyramid) |
  520. | `/styleseed audit` | Nielsen's 10 usability heuristics evaluation |
  521. | `/styleseed copy` | Generate UX microcopy (buttons, errors, empty states, toasts) |
  522. | `/styleseed feedback` | Add loading/success/error/empty states to any component |
  523. ### Optional repository-only learning extension
  524. `/ss-learn` is not part of the single-skill core or the public `npx skills add` path. Its source lives
  525. under `extensions/learning/` for security development and local contract testing. It records a generalized lesson only after a
  526. person asks for capture, then requires separate caller attestations before acceptance and before
  527. preparing a share package. Known high-risk identity patterns are blocked; this is a guardrail, not
  528. an anonymization guarantee; review the exact package before exposure. Source code, prompts,
  529. screenshots, URLs, brand tokens, and arbitrary extra fields are rejected. The prepared package
  530. stays local and untransmitted. The extension source includes a development-only bridge, but it must
  531. remain disabled until a host-owned proof adapter is verified. If it is ever enabled, one exact approved
  532. package would become visible to the connected client/model after a separate one-time grant. Neither the
  533. CLI nor the bridge uploads to a registry or changes core rules automatically.
  534. ### Codex plugin package
  535. The repository now includes a repository development `.codex-plugin/plugin.json` package boundary
  536. for local testing alongside the same core skill. The implemented default/core install contains
  537. neither `ss-learn` nor a learning MCP. Public directory release is not verified. `npx skills add
  538. bitjaru/styleseed` remains the portable released installation path today.
  539. ### Example Workflow
  540. ```bash
  541. /styleseed setup # Pick skin, configure project
  542. /styleseed page Dashboard # Scaffold main page
  543. /styleseed copy "dashboard" # Generate all microcopy
  544. /styleseed feedback src/Dashboard # Add loading/error states
  545. /styleseed audit src/Dashboard # Check UX quality
  546. /styleseed lint src/Dashboard # Quick violation scan
  547. /styleseed review src/Dashboard # Deep design compliance check
  548. /styleseed update # Pull latest engine updates
  549. ```
  550. ### Example Prompts
  551. **New project:**
  552. ```
  553. Refer to https://github.com/bitjaru/styleseed — read engine/CLAUDE.md
  554. and engine/DESIGN-LANGUAGE.md. Use skins/stripe/theme.css for colors.
  555. Build a SaaS dashboard with revenue, users, and activity.
  556. ```
  557. **Add a page (engine already in project):**
  558. ```
  559. Follow CLAUDE.md and DESIGN-LANGUAGE.md rules.
  560. Create a settings page with profile, notifications, and danger zone.
  561. Run /styleseed review when done.
  562. ```
  563. **Improve existing page:**
  564. ```
  565. Refactor src/Dashboard.tsx to follow DESIGN-LANGUAGE.md.
  566. Check visual rhythm (rule 61) and KPI variation (rule 62).
  567. ```
  568. **Update engine:**
  569. ```
  570. /styleseed update
  571. ```
  572. ## Tech Stack
  573. React 18 · TypeScript · Tailwind CSS v4 · Radix UI · Vite 6 · Lucide Icons · CVA
  574. ## StyleSeed vs. the alternatives
  575. | | StyleSeed | shadcn/ui | Tailwind UI | Material UI | Generic AI output |
  576. |---|---|---|---|---|---|
  577. | Components | ✅ 48 | ✅ 50+ | ✅ | ✅ | ❌ |
  578. | Design **judgment** (when to use what) | ✅ 74 rules | ❌ | ❌ | Partial | ❌ |
  579. | Claude Code / Cursor integration | ✅ 1 skill | ❌ | ❌ | ❌ | — |
  580. | Brand skins (Toss, Stripe, Linear...) | ✅ | ❌ | ❌ | ❌ | ❌ |
  581. | Price | Free (MIT) | Free | $299+ | Free | — |
  582. | Works *with* AI coding tools | ✅ | Indirect | Indirect | Indirect | — |
  583. **TL;DR:** component libraries supply implementation material. StyleSeed adds recorded design
  584. decisions and workflows for applying and checking them. Its goal is repeatable expert judgment,
  585. not replacing the designer or the project's component library.
  586. ## FAQ
  587. **Q: Why does Claude Code / Cursor generate ugly UI?**
  588. 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.
  589. **Q: Is this a shadcn/ui replacement?**
  590. 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.
  591. **Q: Does it work with Cursor too?**
  592. Yes. The 74 design rules live in a `.cursorrules` file and `CLAUDE.md`. Cursor reads them automatically.
  593. **Q: How is this different from awesome-design-md?**
  594. 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.
  595. **Q: Can I use it for a non-fintech app?**
  596. Yes. The engine is brand-agnostic. Pick any skin, swap the brand color, ship.
  597. ## Documentation
  598. Full docs in the **[Wiki](../../wiki)** — design rules reference, composition recipes, chart guides, skills reference.
  599. Where the project is headed: **[ROADMAP.md](ROADMAP.md)**.
  600. ## Field notes — the thinking behind the rules
  601. Longer-form writing on why AI-built UI looks the way it does (and what actually fixed it):
  602. - **[Why AI-Generated UIs Look 'Off' — and the One Principle That Fixes It](https://dev.to/kiwibreaksme/why-ai-generated-uis-look-off-and-the-one-principle-that-fixes-it-4j20)** — coherence, the "one value per axis" law, with copy-paste CSS. ([한국어판](https://dev.to/kiwibreaksme/aiga-mandeun-uiga-eodinga-eosaeghan-iyu-geurigo-geugeol-gocineun-han-gaji-weoncig-5e4p) — 3.5k+ reads)
  603. - **[I catalogued every tell that makes a UI look AI-generated. My own tool kept failing the test.](https://dev.to/kiwibreaksme/i-catalogued-every-tell-that-makes-a-ui-look-ai-generated-my-own-tool-kept-failing-the-test-n52)** — the tells taxonomy + the 58/100 self-own.
  604. - **[AI가 만든 UI, 보여주기 전에 채점시켜라](https://dev.to/kiwibreaksme/aiga-mandeun-ui-boyeojugi-jeone-caejeomsikyeora-geiteureul-mandeulgo-nae-raendingbuteo-ddeoleojin-iyagi-ea7)** *(KR)* — why rules alone failed and the enforced gate was the fix.
  605. - **[Your Vibe-Coded App Looks Ugly. Here's What I Did About It.](https://dev.to/kiwibreaksme/your-vibe-coded-app-looks-ugly-heres-what-i-did-about-it-2nb4)** — the origin story.
  606. ## Contributing
  607. StyleSeed is a **living judgment framework** — the rules aren't carved in stone. If you use it and
  608. find a pattern that reliably makes UI better, teach it to everyone's AI by proposing it as a rule.
  609. ### ⭐ Propose a design rule (the heart of it)
  610. A good rule is a **decision + the reason it works**, written so a model can apply it — not an opinion.
  611. ```markdown
  612. **Decision:** Keep equivalent metrics comparable.
  613. **Applies to:** Monitoring or comparison tasks.
  614. **Allowed variation:** Repeated panels, aligned rows, or small multiples.
  615. **Failure case:** Decorative chart changes make equivalent values harder to compare.
  616. **Verify:** Check labels, units, scale, period, and the actual comparison task.
  617. **Evidence:** Cite inspected examples and distinguish observation from hypotheses.
  618. ```
  619. Open a **["Propose a design rule"](https://github.com/bitjaru/styleseed/issues/new?template=design_rule.yml)**
  620. issue, or PR it into `engine/DESIGN-LANGUAGE.md` (visual/layout) or `engine/VISUAL-CRAFT.md` (craft &
  621. coherence). The judgment compounds as the community adds to it.
  622. ### Create a New Skin
  623. Just a `theme.css` + `skin.json`:
  624. ```bash
  625. mkdir skins/your-brand
  626. cp skins/toss/theme.css skins/your-brand/theme.css # copy a skin as a starting point
  627. # Change the --brand color and other values
  628. ```
  629. ### Improve the Engine
  630. Better rules → better AI output: more specific design rules, new pattern components, accessibility
  631. improvements, new AI skills.
  632. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full rule format and quality checklist.
  633. ## Updating
  634. Already using StyleSeed? Check the exact rule/skill revision first:
  635. ```bash
  636. # Claude Code: /styleseed update
  637. # Codex: $styleseed update
  638. ```
  639. `ss-update` compares the installed `engineRevision`, the revision recorded in
  640. `.styleseed/manifest.json`, and the published revision. A matching semantic version alone is not
  641. enough. Refresh through the original install channel, then re-resolve and inspect the bundle diff.
  642. **Preserved by the update contract:** `STYLESEED.md`, app code, tokens, assets, customized
  643. components, and project-owned `AGENTS.md` / `CLAUDE.md` / `.cursorrules`.
  644. Full guide: [engine/UPDATE.md](engine/UPDATE.md)
  645. **Get notified:** Click **Watch** → **Custom** → **Releases** on this repo.
  646. ## License
  647. [MIT](LICENSE)
  648. ## Acknowledgments
  649. - Design language inspired by [Toss](https://toss.im)
  650. - Components based on [shadcn/ui](https://ui.shadcn.com/)
  651. - Brand skins sourced from [awesome-design-md](https://github.com/VoltAgent/awesome-design-md)
  652. - UX principles from [Laws of UX](https://lawsofux.com/) and [Nielsen Norman Group](https://www.nngroup.com/)
  653. ### Update reminders and an optional freshness gate
  654. After a one-time refresh, StyleSeed skills require a read-only revision check at the first
  655. workflow of each project/task session. Outdated installs recommend `$styleseed update` (Claude:
  656. `/styleseed update`), including changes that keep the same version number. Updates preserve project
  657. design decisions; offline checks are reported as unknown. Old installed skills cannot receive
  658. this instruction until updated once.
  659. For CI/tasks that must use the current installed channel, run the installed
  660. `ss-update/scripts/check-update.mjs --project-root . --require-current --json` before your build.
  661. It exits 1 on outdated/unverifiable installs or any stale registry artifact; it never installs
  662. anything. Pinned projects can keep diagnostic mode without `--require-current`. See the
  663. [update preflight contract](engine/.claude/skills/styleseed/workflows/ss-update/references/update-preflight.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.