Creating New Seeds

Creating New Seeds

StyleSeed ships with the toss seed, but the architecture supports multiple design languages. This guide explains how to contribute a new seed.

---

What Is a Seed?

A seed is a complete, self-contained design system package that an AI coding tool can use to generate consistent UI. It contains:

Component	Purpose	Required?
DESIGN-LANGUAGE.md	Visual rules (the "why" and "what")	Yes
CLAUDE.md	AI assistant guide (the "how")	Yes
README.md	Human-readable overview	Yes
components/ui/	Primitive components	Yes
components/patterns/	Composed patterns	Yes
css/	Theme and styling	Yes
tokens/	JSON design tokens	Yes
scaffold/	Project template files	Recommended
icons/	Custom icon set	Optional
docs/	Showcase, token visualizer	Optional

---

Step-by-Step: Creating a New Seed

Step 1: Choose Your Design Language

Pick a distinct visual style. Good seeds are opinionated and specific:

Good Seed Ideas	Why
"Material You" style	Google's dynamic color system
"Linear" style	Minimal, monochrome, sharp edges
"Stripe" style	Clean gradients, generous whitespace
"Notion" style	Content-first, subtle UI
"Vercel" style	Dark-first, developer-focused

Avoid generic "bootstrap-like" seeds -- the value is in having a strong, specific visual opinion.

Step 2: Extract Design Rules

Study your reference design and document every rule you can find. The toss seed has 69 rules across these categories:

1. Color philosophy (accent strategy, grayscale levels, impact colors)
2. Typography (size scale, number-unit ratios, label conventions)
3. Layout (section types, spacing system, card structure)
4. Charts and data visualization
5. Interactions and transitions
6. Forbidden patterns
7. Page composition
8. Accessibility
9. Dark mode
10. UX writing tone

Minimum rule count: Aim for at least 30 rules. Fewer than that usually means the design language isn't specific enough.

Step 3: Write DESIGN-LANGUAGE.md

This is the most important file. Structure it like the toss seed:

# [Seed Name] Design Language Guide
> Extracted from [reference design/product]

## 1. Color Philosophy
### Key Color Principle
- What is the accent strategy?
- How many accent colors?
- Grayscale levels?

## 2. Typography
### Size Scale
| Token | Size | Use |
|-------|------|-----|

### Number Formatting
- How are large numbers displayed?
- Number-unit size ratio?

## 3. Layout
### Section Types
- What are the page building blocks?
- Spacing system?

... (continue for all categories)

## N. Forbidden Patterns
- What should NEVER be done?

## Summary
### Core Principles (numbered list)
### Forbidden (numbered list)

Step 4: Build the Component Library

Primitives (components/ui/)

Start with these essentials (minimum 15):

button, card, input, textarea, select, checkbox,
radio-group, switch, label, badge, avatar, separator,
skeleton, dialog, tabs, tooltip, form

Every component must follow these conventions:

import * as React from "react"
import { cn } from "./utils"

function MyComponent({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="my-component"
      className={cn("base-classes", className)}
      {...props}
    />
  )
}

export { MyComponent }

Rules:

• data-slot attribute on every component
• cn() for className merging (never template literals)
• CVA for variant management
• React.ComponentProps<> for type inference
• className prop support on all visual components

Patterns (components/patterns/)

Build at least 8 composed patterns:

page-shell     -- Page wrapper with max-width and background
top-bar        -- App header with logo, actions, subtitle
bottom-nav     -- Bottom navigation with tabs
stat-card      -- KPI metric card
hero-card      -- Large hero metric
section-card   -- Generic section wrapper
list-item      -- List row with status and trailing content
empty-state    -- Zero-data placeholder

Step 5: Define Design Tokens

CSS Tokens (css/theme.css)

:root {
  /* Brand */
  --brand: #your-accent;

  /* Grayscale */
  --text-primary: #...;
  --text-secondary: #...;
  /* ... */

  /* Surfaces */
  --surface-page: #...;
  --card: #...;
  /* ... */

  /* Shadows */
  --shadow-card: ...;
  /* ... */
}

JSON Tokens (tokens/)

Create JSON files for cross-platform consumption:

tokens/
  colors.json
  typography.json
  spacing.json
  radii.json
  shadows.json
  motion.json

Format:

{
  "color": {
    "brand": { "value": "#721FE5", "type": "color" },
    "text": {
      "primary": { "value": "#3C3C3C", "type": "color" }
    }
  }
}

Step 6: Write CLAUDE.md

This file tells the AI how to use your seed. Include:

1. Quick start (copy instructions)
2. Token customization guide
3. Component import patterns
4. Component conventions
5. Pattern component examples with code
6. Tech stack
7. File structure
8. Forbidden practices
9. Slash command reference

Step 7: Create the Scaffold

scaffold/ contains project template files:

scaffold/
  package.json      -- Dependencies
  vite.config.ts    -- Build config
  tsconfig.json     -- TypeScript config
  postcss.config.mjs
  index.html        -- Entry HTML with viewport-fit=cover

---

Quality Checklist

Before submitting a new seed, verify:

Completeness

• DESIGN-LANGUAGE.md has 30+ rules
• CLAUDE.md has setup instructions and all component examples
• README.md describes the seed and its origin
• At least 15 UI primitives
• At least 8 pattern components
• CSS theme with all semantic tokens
• JSON tokens for all categories
• Dark mode support

Consistency

• Every component has data-slot
• Every component uses cn() for className
• Every component accepts className prop
• All colors reference CSS variables (no hardcoded hex in components)
• Spacing follows a consistent scale
• Typography scale is documented

Distinctiveness

• Visual style is clearly different from existing seeds
• Rules are specific, not generic
• Forbidden patterns are documented
• The seed produces recognizably different UI from other seeds

Testability

• npm install && npm run dev works from scaffold
• All components render without errors
• Dark mode toggles correctly
• Accessibility basics pass (touch targets, contrast, focus rings)

---

File Structure of a Complete Seed

seeds/
  my-seed/
    README.md
    CLAUDE.md
    DESIGN-LANGUAGE.md
    tokens.ts
    css/
      fonts.css
      theme.css
      base.css
      index.css
    tokens/
      colors.json
      typography.json
      spacing.json
      radii.json
      shadows.json
      motion.json
    components/
      ui/
        utils.ts
        button.tsx
        card.tsx
        input.tsx
        ... (15+ primitives)
      patterns/
        page-shell.tsx
        top-bar.tsx
        bottom-nav.tsx
        stat-card.tsx
        ... (8+ patterns)
    scaffold/
      package.json
      vite.config.ts
      tsconfig.json
      postcss.config.mjs
      index.html
    icons/           # Optional
      index.tsx
    docs/            # Optional
      Showcase.tsx
      design-tokens.html

---

Submitting

1. Fork the styleseed repository
2. Create your seed directory under seeds/your-seed-name/
3. Ensure all checklist items pass
4. Submit a pull request with:
   • Seed name and description
   • Reference design/product
   • Screenshots of generated UI
   • Test results (build, render, a11y)

---

Tips

• Start with DESIGN-LANGUAGE.md: Write the rules before building components. The rules ARE the seed; components are just their implementation.
• Be opinionated: A seed that says "maybe use 8px or 12px spacing" is useless. Say "always 6px multiples, period."
• Document forbidden patterns: Knowing what NOT to do is as valuable as knowing what to do.
• Test with AI: Generate pages using your seed with Claude Code. If the AI produces inconsistent results, your rules need to be more specific.
• Keep the rule count manageable: 40-80 rules is the sweet spot. Fewer is too vague; more becomes noise.