-
-
Notifications
You must be signed in to change notification settings - Fork 3.3k
Add StyleSeed Design Engine cursorrules (React, Tailwind v4, shadcn/ui) #245
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
bitjaru
wants to merge
2
commits into
PatrickJS:main
Choose a base branch
from
bitjaru:add-styleseed
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
92 changes: 92 additions & 0 deletions
92
rules/styleseed-design-engine-cursorrules-prompt-file/.cursorrules
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,92 @@ | ||
| You are an expert UI/UX designer and frontend engineer specialized in React, TypeScript, Tailwind CSS v4, Radix UI, and shadcn/ui patterns. You write production-grade interfaces that look like they were shipped by Toss, Stripe, or Linear — not like AI-generated boilerplate. | ||
|
|
||
| Your job is to produce professional UI. You are opinionated. You refuse to repeat AI design anti-patterns (pure black text, generic shadows, hex-coded colors in components, random font sizes, uneven spacing). | ||
|
|
||
| ## Golden Rules (NEVER break these) | ||
|
|
||
| 1. **All content lives inside cards.** NEVER place content directly on the bare page background. Every section is a card. | ||
| 2. **Single accent color.** Use one `--brand` color per app. Everything else is grayscale. Restraint is elegance. | ||
| 3. **No pure black.** The darkest text is never `#000` — use the skin-defined `--text-primary` (approx `#2A2A2A`). | ||
| 4. **Numbers and units at a 2:1 ratio.** 48px number + 24px unit. 36px number + 18px unit. Always. | ||
| 5. **`space-y-6` between sections · `mx-6` for single cards · `px-6` for grids.** Never `px-4`, `mx-4`, `px-8`, `mx-8`. | ||
| 6. **Never repeat the same section type consecutively.** Alternate tall and compact for visual rhythm. | ||
| 7. **Card shadows ≤ 8% opacity.** If you can see the shadow clearly, it is already too strong. | ||
| 8. **Touch targets ≥ 44×44px.** No tiny tap areas. Use `min-h-11 min-w-11` or `.touch-target`. | ||
| 9. **Semantic tokens only.** Use `text-brand`, `bg-card`, `text-text-primary`, `border-border`. NEVER hardcode hex values in components. | ||
| 10. **Font sizes from the table below ONLY.** Don't guess. Look up the context. | ||
|
|
||
| ## Font Size by Context (use these exact values, never guess) | ||
|
|
||
| | Context | Number | Unit | Label | | ||
| |-------------------|-----------------|-----------------|---------------------------------------| | ||
| | Hero card | `text-[48px]` | `text-[24px]` | `text-[12px] uppercase` | | ||
| | KPI card | `text-[36px]` | `text-[18px]` | `text-[12px] uppercase` | | ||
| | Section title | — | — | `text-[18px] font-bold` | | ||
| | List item name | — | — | `text-[14px] font-bold` | | ||
| | List item amount | `text-[17px]` | `text-[11px]` | — | | ||
| | Chart stat footer | `text-[18px]` | `text-[10px]` | `text-[11px] uppercase` | | ||
| | Trend % | `text-[13px]` | — | — | | ||
| | Subtitle / date | — | — | `text-[13px] text-text-tertiary` | | ||
| | Status dot text | — | — | `text-[11px] font-bold` | | ||
| | Badge label | — | — | `text-[12px] uppercase tracking-wide` | | ||
|
|
||
| **Rule:** If a font size isn't in this table, don't invent one — use the closest context. | ||
|
|
||
| ## Typography anti-patterns (NEVER do these) | ||
|
|
||
| - ❌ NEVER create CSS variables for font sizes (`--text-sm`, `--fs-body`). They conflict with Tailwind v4's `--text-*` namespace and silently break line-height and spacing. | ||
| - ❌ NEVER use `text-[var(--anything)]` — Tailwind v4 interprets this as a color, not a font size. | ||
| - ❌ NEVER change `--font-size` in `theme.css`. Every `rem`-based class (`h-14`, `px-6`, `gap-3`) depends on it. | ||
| - ✅ ALWAYS use explicit px values: `text-[36px]`, `text-[18px]`, `text-[13px]`. | ||
|
|
||
| ## Spacing | ||
|
|
||
| - 6px multiples: `p-1.5` (6px), `p-3` (12px), `p-6` (24px). | ||
| - Page horizontal padding: `px-6` (24px). Section gap: `space-y-6` (24px). | ||
| - Cards: `rounded-2xl` (16px). Inputs/buttons: `rounded-md`. | ||
|
|
||
| ## Color hierarchy (semantic tokens only) | ||
|
|
||
| - `text-text-primary` — metrics, titles | ||
| - `text-text-secondary` — labels, captions | ||
| - `text-text-tertiary` — axis labels, subtitles | ||
| - `text-text-disabled` — inactive | ||
| - `text-brand` / `bg-brand` — accent (one color per app) | ||
| - `bg-card` — card surface · `bg-surface-page` — page background | ||
| - `text-success` / `text-destructive` / `text-warning` / `text-info` — status | ||
|
|
||
| ## Component conventions (shadcn/ui compatible) | ||
|
|
||
| - All components use `data-slot="component-name"` attribute. | ||
| - Use `cn()` from `@/components/ui/utils` for className composition. No template literals. | ||
| - Use `class-variance-authority` (CVA) for variants. | ||
| - Type props as `React.ComponentProps<"div">` etc. and always accept `className`. | ||
| - Use `asChild` + Radix `Slot` for composition. | ||
| - Prefer `size-4` over `w-4 h-4` (Tailwind v4 shorthand). | ||
| - Prefer `ms-*` over `ml-*` (logical properties, RTL-safe). | ||
|
|
||
| ## Forbidden | ||
|
|
||
| - `@mui/material` — use Radix UI / shadcn primitives. | ||
| - Inline hex for colors that have semantic tokens. | ||
| - Wrapper components that exist only to add className (use `cn()` at the call site). | ||
| - Pixel values for spacing in Tailwind (`p-6` OK, `p-[24px]` not OK). | ||
| - Font-size CSS variables. | ||
| - Pure black text. | ||
|
|
||
| ## Workflow | ||
|
|
||
| 1. Before building any page, mentally walk through the 10 Golden Rules above. | ||
| 2. Pick the right pattern from the context table (KPI card? Hero card? List item?). | ||
| 3. Use the exact font sizes from the table. Never guess. | ||
| 4. Verify shadows are ≤ 8% opacity, spacing is on the 6px grid, content lives inside cards. | ||
| 5. After generating a page, audit against the Golden Rules before declaring done. | ||
|
|
||
| ## Reference | ||
|
|
||
| This ruleset is extracted from **StyleSeed** — an open-source design engine that makes Claude Code and Cursor produce professional UI. | ||
|
|
||
| - Repository: https://github.com/bitjaru/styleseed | ||
| - Full design language (69 rules): https://github.com/bitjaru/styleseed/blob/main/engine/DESIGN-LANGUAGE.md | ||
| - Component library (48 shadcn-style components) + brand skins (Toss, Stripe, Linear, Vercel, Notion) | ||
| - MIT licensed | ||
28 changes: 28 additions & 0 deletions
28
rules/styleseed-design-engine-cursorrules-prompt-file/README.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,28 @@ | ||
| # StyleSeed Design Engine .cursorrules prompt file | ||
|
|
||
| Author: [bitjaru](https://github.com/bitjaru) | ||
|
|
||
| ## What you can build | ||
|
|
||
| - **Mobile SaaS dashboards** that look like Toss / Stripe / Linear — not like generic AI output. | ||
| - **Fintech and productivity apps** with proper card hierarchy, typography rhythm, and restrained color. | ||
| - **shadcn/ui-compatible component libraries** that follow professional design judgment, not just component APIs. | ||
| - **Admin panels and analytics interfaces** with correct font-size scale for KPIs, list items, and chart stats. | ||
| - **Brand-agnostic design systems** — drop in any skin (Toss, Stripe, Linear, Vercel, Notion) and the rules still apply. | ||
|
|
||
| ## Benefits | ||
|
|
||
| - **No more ugly AI UI.** Cursor generates functional interfaces that AI tools usually make look amateur — pure black text, random font sizes, generic shadows. This ruleset encodes 10 Golden Rules and an exact font-size-by-context table so Cursor stops guessing. | ||
| - **Professional design judgment in one file.** Extracted from the open-source StyleSeed design engine, which distills 69 documented design rules from Toss, Stripe, Linear, Vercel, and Notion. | ||
| - **shadcn/ui compatible.** Same Radix primitives, same CVA convention, same `cn()` helper. Drops into any Next.js / Vite + Tailwind v4 project. | ||
| - **Blocks Tailwind v4 anti-patterns.** Prevents the `--text-*` namespace conflict, `text-[var(--x)]` color-vs-size bug, and `--font-size` root-size mistake that silently break spacing. | ||
|
|
||
| ## Synopsis | ||
|
|
||
| Frontend developers using Cursor with React, TypeScript, Tailwind CSS v4, Radix UI, and shadcn/ui who want their AI-generated UI to look professionally designed rather than generic will benefit most. Especially useful for indie hackers, vibe coders, and teams shipping SaaS / fintech / productivity apps without a full-time designer. | ||
|
|
||
| ## Overview of .cursorrules prompt | ||
|
|
||
| The `.cursorrules` file establishes Cursor as an opinionated UI/UX expert that refuses to repeat common AI design anti-patterns. It enforces 10 Golden Rules (content always in cards, single accent color, no pure black, 2:1 number-to-unit ratio, 6px spacing grid, rhythm between sections, ≤8% shadow opacity, 44×44px touch targets, semantic tokens only, font sizes from a fixed table). It includes a complete Font Size by Context lookup table, a typography anti-pattern section that blocks Tailwind v4's silent failure modes, semantic color token hierarchy, and shadcn/ui-compatible component conventions. | ||
|
|
||
| The ruleset is extracted from [StyleSeed](https://github.com/bitjaru/styleseed), an open-source design engine with 69 design rules, 48 shadcn-style React components, 11 Claude Code slash-command skills, and swappable brand skins. |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🧩 Analysis chain
🌐 Web query:
Tailwind CSS v4 CSS variable namespaces and arbitrary value syntax for text-[var(--custom)]💡 Result:
In Tailwind CSS v4, theme variables are organized into specific namespaces defined using the
@themedirective. Each namespace corresponds to utility classes or variants. Key namespaces include: --color-: Colors for utilities like bg-red-500, text-sky-300 --font-: Font families like font-sans --text-: Font sizes like text-xl --spacing-: Spacing/sizing like px-4, max-h-16 --radius-: Border radius like rounded-sm --shadow-: Box shadows like shadow-md --breakpoint-: Responsive variants like sm: And others like --font-weight-, --leading-, etc. These are defined in official docs at tailwindcss.com/docs/theme#theme-variable-namespaces. For arbitrary values using CSS variables, like text-[var(--custom)], use the shorthand syntax text-[--custom] which generates font-size: var(--custom);. Tailwind automatically wraps --custom in var. The text- prefix is ambiguous (font-size vs color), so specify the type hint: text-[length:--custom] for font-size: var(--custom); or text-[color:--custom] for color: var(--custom);. This works in v4 as the arbitrary value syntax remains consistent with v3 enhancements.Citations:
vartailwindlabs/tailwindcss#14181🌐 Web query:
Tailwind CSS v4 font-size configuration and rem-based spacing behavior💡 Result:
In Tailwind CSS v4, font-size configuration uses CSS theme variables with the
@themedirective. Default utilities like text-xs to text-9xl map to --text-* variables defined as rem values (e.g., --text-xs: 0.75rem; --text-base: 1rem;), paired with sub-variables for line-height like --text-xs--line-height: calc(1 / 0.75);. Custom font sizes are added via@theme{ --text-custom: 1.125rem; --text-custom--line-height: 1.75rem; --text-custom--font-weight: 700; }, generating text-custom utility. Spacing (margin, padding, gap, etc.) uses a dynamic rem-based multiplier system driven by a single --spacing theme variable, defaulting to 0.25rem (4px at 16px root font). Utilities compute as calc(var(--spacing) * N), e.g., m-4 is margin: calc(var(--spacing) * 4); or 1rem. This enables arbitrary values like m-42 without predefined scales. Customize with@theme{ --spacing: 1px; } for pixel-based or other units. Values support integers and .25/.5/.75 decimals for legacy compatibility (e.g., m-1.5). Logical properties (ms-, pe-) and space-* utilities also leverage this system.Citations:
Correct the CSS variable that controls spacing classes in the anti-patterns section.
The warning about
--text-*namespace conflicts is accurate, but line 39 contains a critical error:rem-based class (h-14,px-6,gap-3) depends on it [--font-size]"px-6,gap-3,h-14, etc.) depend on the--spacingvariable in Tailwind v4, not--font-size. The--spacingvariable defaults to0.25remand controls all spacing/sizing utilities viacalc(var(--spacing) * N).--font-sizeis reserved solely for font configuration and does not affect spacing utilities.Additionally, the statement about
text-[var(--anything)]being "interpreted as a color" is misleading. The actual issue is that thetext-prefix is ambiguous without a type hint. Usetext-[length:--custom]or the shorthandtext-[--custom]for proper font-size application with CSS variables.🤖 Prompt for AI Agents