Complete checklist for adding a new design style to StyleKit. All items are REQUIRED - do not skip any step.
- Define style slug (kebab-case, e.g.,
warm-dashboard) - Prepare 3-5 primary colors with hex codes
- Identify 5-10 characteristic visual traits
- Determine styleType:
visual|layout - Choose category:
modern|retro|minimal|expressive(seelib/styles/meta-types.ts)
-
lib/styles/{slug}.ts- Main DesignStyle objectslug,name,nameEn,descriptioncover:/styles/{slug}.svgstyleType,tags,categorycolors: primary, secondary, accent[]keywords: Chinese search termsphilosophy: Design principles (multi-line string)doList: 6-8 required patternsdontList: 4-6 forbidden patternscomponents: button, card, input, nav, hero, footer (with code snippets)globalCss: CSS custom propertiesaiRules: Comprehensive AI generation guidelinesexamplePrompts: 2-3 example use cases
-
lib/styles/{slug}-tokens.ts- AI-consumable Tailwind mappings- Use
createStyleTokens()from./token-defaults(provides sensible defaults via deep-merge) - Only override fields that differ from defaults
- Required override sections:
colors: background, text, button (style-specific)forbidden: classes to never userequired: classes that must be used- Required utilities must occur in every recipe variant and parameter combination.
- Keep optional colors, sizes and interactive-only treatments in recipes.
- Keep any curated
lint-rules.tsrequired entries identical to token requirements. - Review changes with
pnpm run align:recipe-required --report .tmp/required-review.json; only use--writeafter reviewing the proposed per-style decisions.
- Optional overrides (inherit defaults if omitted):
border: radius, width, styleshadow: default, hover variantsinteraction: hover, active, focus statestypography: fonts, sizes, weightsspacing: padding, margin, gap
- Example:
import { createStyleTokens } from "./token-defaults"; export const myStyleTokens = createStyleTokens({ colors: { background: { primary: "bg-black" } }, border: { radius: "rounded-none" }, forbidden: { classes: ["rounded-lg"], patterns: [], reasons: {} }, required: { button: ["font-mono"], card: ["border-2"], input: ["bg-transparent"] }, });
- Use
-
lib/recipes/{slug}.ts- Component recipes- Use
createStyleRecipes()and helpers from./factory - MUST include: button, card, input (minimum)
- Optional: nav, badge, table, alert, hero, footer, etc.
- Available helpers:
sizeParam({ sm, md, lg })- Size select parameterpaddingParam({ sm, md, lg })- Padding select parameterfullWidthParam- Full width boolean toggleinteractiveParam(classes, default?)- Interactive booleanvisibleParam- Visibility togglebuttonSlots(label?),cardSlots(title?, content?),inputSlots(placeholder?)- Common slot presetschildrenSlot(),labelSlot(default),iconSlot()- Single-slot presetsdefaultVariant,variant(id, label, labelZh, classes)- Variant builders
- Example:
import { sizeParam, fullWidthParam, buttonSlots, variant, createStyleRecipes } from "./factory"; export const myStyleRecipes = createStyleRecipes("my-style", "My Style", { button: { id: "button", name: "Button", nameZh: "按钮", description: "My style button", skeleton: { element: "button", baseClasses: ["font-bold", "border-2"] }, parameters: [sizeParam({ sm: "px-3 py-1", md: "px-5 py-2", lg: "px-7 py-3" }), fullWidthParam], variants: { primary: variant("primary", "Primary", "主要", ["bg-black text-white"]), }, slots: buttonSlots("Click"), states: { hover: ["hover:opacity-80"] }, }, // ... card, input, etc. });
- Use
-
lib/design-spec/samples/{slug}.ts- Full bilingualDesignSpecderived from the style definition and showcase - Register the spec in
lib/design-spec/registry.ts - Set
completeness: "full"and cover every section used by the shared renderer - Verify the style page previews, copies and downloads the same complete
design.md - After registration, run
pnpm run check:catalog- the publish preflight also requires a fullDesignSpecfor every curated style
Preferred workflow: submit one StyleScaffoldInput through publishStyle from
@/lib/style-publication. It plans and validates its file and registry projections before commit and rolls back a
partial commit. The authored DesignSpec and its registration in phase 1.4 remain separate required work;
the publisher does not generate a replacement design document. Run the full test suite before merging.
Treat the registry items below as review assertions or manual recovery steps, not
independent publication operations. The input must contain an explicitly approved previewModule;
publication never invents a generic preview.
-
lib/styles/registry.ts- Add import statement:
import { styleName } from "./{slug}"; - Add to
stylesarray:styleName,
- Add import statement:
-
lib/styles/meta-registry.ts- Add entry to
stylesMetaarray with:slug,name,nameEn,descriptioncover:/styles/{slug}.svgstyleType,tags,categorycolors: primary, secondary, accent[]keywords: Chinese search terms
- Add entry to
-
lib/styles/tokens-registry-data.ts- Add import statement:
import { styleNameTokens } from "./{slug}-tokens"; - Add to
styleTokensRegistry:"{slug}": styleNameTokens,
- Add import statement:
-
lib/recipes/registry.ts- Add import statement:
import { styleNameRecipes } from "./{slug}"; - Add to
recipeRegistryobject:"{slug}": styleNameRecipes,
- Add import statement:
-
lib/style-preview/styles/{slug}.tsx- Export preview renderers explicitly authored and approved for this style
- Keep the existing visual contract unchanged when editing an approved style
- Include
coverPreview; addbutton,card, andinputwhen the style supports them - Pick a cover composition from
STYLE_COVER_ARCHETYPES.md; the cover must not print the style's own name - Do not leave the generated TODO placeholder in a publication request
-
lib/style-preview/registry.ts- Add the preview module import and
{slug}entry
- Add the preview module import and
-
lib/style-preview/delivery.ts- Add the lazy loader and
{slug}tostylePreviewSlugs
- Add the lazy loader and
- Create
app/styles/{slug}/showcase/directory
-
app/styles/{slug}/showcase/page.tsx- Dynamic import with loading skeleton
- Loading skeleton styled to match theme colors
- Example:
import dynamic from "next/dynamic"; const ShowcaseContent = dynamic(() => import("./_content"), { loading: () => ( <div className="min-h-screen bg-[#BACKGROUND] flex items-center justify-center"> <div className="text-center"> <div className="inline-block w-8 h-8 border-2 border-[#PRIMARY] border-t-transparent animate-spin rounded-full mb-4" /> <p className="text-[#MUTED]">Loading...</p> </div> </div> ), }); export default function StyleShowcase() { return <ShowcaseContent />; }
-
app/styles/{slug}/showcase/_content.tsx"use client"directive at top- 400-600 lines minimum
- 12+ distinct sections
- 2+ useState hooks for interactivity (tabs, dropdowns, pagination, etc.)
- Required sections:
- Navigation header
- Hero section with title
- Color palette display
- Typography showcase
- Buttons (4+ variants)
- Cards (3+ variations)
- Form elements (input, textarea, select)
- Tabs or navigation component
- Badges/tags
- Progress bars or indicators
- Alerts (info, success, warning, error)
- Table with data
- Blockquote/testimonial
- Dividers/decorators
- Rules summary (do/don't)
- Footer
-
public/styles/{slug}.svg- Dimensions:
1200x630viewBox - MUST show miniaturized UI components (NOT just style name)
- Four-corner layout with variety of components:
- Top-left: Card with heading + text
- Top-right: Another card or component
- Bottom-left: Buttons or badges
- Bottom-right: Form element or card
- Central title area with style name
- Style-specific effects:
- Shadows (drop-shadow, soft, hard)
- Gradients
- Patterns (grids, dots, textures)
- Borders (thick, thin, dashed)
- Decorative elements
- Dimensions:
Reference examples:
| Style | Approach |
|---|---|
neo-brutalist.svg |
Hard shadows, grid background, bold colors |
neumorphism.svg |
Soft embossed shadows, rounded shapes |
dark-academia.svg |
Leather texture, gold accents, serif headings |
- Run
pnpm run typecheck- generates current route types and reports no errors
- Run
pnpm run check:recipe-lint- no forbidden or required contract violations - Run
pnpm test- all tests passstyles-consistency.test.tsvalidates index + meta alignmentstyle-assets.test.tsvalidates SVG + coverPreview existencerecipes-integrity.test.tsvalidates recipe structure
- Run
pnpm run dev - Visit
/styles- verify style appears in gallery with correct cover - Visit
/styles/{slug}- verify docs page loads - Visit
/styles/{slug}/showcase- verify showcase renders with all sections - Test responsive behavior (mobile/tablet/desktop)
| Phase | Action | File |
|---|---|---|
| 1.1 | CREATE | lib/styles/{slug}.ts |
| 1.2 | CREATE | lib/styles/{slug}-tokens.ts |
| 1.3 | CREATE | lib/recipes/{slug}.ts |
| 1.4 | CREATE | lib/design-spec/samples/{slug}.ts |
| 1.4 | MODIFY | lib/design-spec/registry.ts |
| 2.1 | MODIFY | lib/styles/registry.ts |
| 2.2 | MODIFY | lib/styles/meta-registry.ts |
| 2.3 | MODIFY | lib/styles/tokens-registry-data.ts |
| 2.4 | MODIFY | lib/recipes/registry.ts |
| 2.5 | CREATE | lib/style-preview/styles/{slug}.tsx |
| 2.6 | MODIFY | lib/style-preview/registry.ts |
| 2.7 | MODIFY | lib/style-preview/delivery.ts |
| 3.1 | CREATE | app/styles/{slug}/showcase/ (directory) |
| 3.2 | CREATE | app/styles/{slug}/showcase/page.tsx |
| 3.3 | CREATE | app/styles/{slug}/showcase/_content.tsx |
| 4.1 | CREATE | public/styles/{slug}.svg |
Total: 8 new files + 7 modified files per style
- Forgetting showcase pages - Always create both
page.tsxand_content.tsx - Cover SVG shows only text - MUST show UI components
- Missing coverPreview in the preview module - Required for gallery preview
- Mismatched slugs - Use exact same slug everywhere
- Missing imports - Remember to add to index.ts files
- Non-interactive showcase - Add useState hooks for tabs, dropdowns, etc.
# Create directories
mkdir -p app/styles/{slug}/showcase
# Files to create
touch lib/styles/{slug}.ts
touch lib/styles/{slug}-tokens.ts
touch lib/recipes/{slug}.ts
touch app/styles/{slug}/showcase/page.tsx
touch app/styles/{slug}/showcase/_content.tsx
touch public/styles/{slug}.svg
# Files to modify
# - lib/styles/registry.ts
# - lib/styles/meta-registry.ts
# - lib/styles/tokens-registry-data.ts
# - lib/recipes/registry.ts
# - lib/style-preview/registry.ts
# - lib/style-preview/delivery.ts