Sourceful Energy

Claude Code Setup

Configure your project to use the Sourceful Design System with Claude Code.

Why use CLAUDE.md?

Claude Code automatically reads CLAUDE.md files in your project root. By adding our template, Claude will automatically:

  • Use components from @sourceful-energy/ui
  • Follow Sourceful design patterns and color tokens
  • Avoid creating custom components when design system components exist
  • Apply correct dark mode and accessibility practices

Setup Steps

1. Install the package

npm install @sourceful-energy/ui

2. Add styles to your app

Import the styles in your root layout or app entry point:

import "@sourceful-energy/ui/styles.css"

3. Add the CLAUDE.md template

Download the template to your project root:

curl -o CLAUDE.md https://raw.githubusercontent.com/srcfl/srcful-design-system/main/CLAUDE.project-template.md

4. Customize for your project

Open CLAUDE.md and add any project-specific context at the bottom. This helps Claude understand your specific codebase patterns.

Template Contents

The template includes:

  • Component quick reference - Table mapping needs to components
  • Import patterns - Correct way to import components and styles
  • Key patterns - Theming, colors, toasts, forms
  • Don't list - Common mistakes to avoid
  • Project notes section - Space for your custom context

Example Prompts

Once set up, you can give Claude Code prompts like:

"Create a form for adding a new site with name, location, and capacity fields"

"Add a card showing battery status with a progress bar"

"Create a data table for displaying device list with sorting"

Claude will automatically use the correct design system components, patterns, and styling.

Reskinning Existing Projects

For existing projects that don't use the design system yet, the CLAUDE.md template includes specific guidelines to ensure Claude doesn't break your existing code.

Critical: CSS Import Order

The design system CSS must be imported before your project's globals.css:

// In your root layout - ORDER MATTERS
import "@sourceful-energy/ui/styles.css"  // FIRST
import "./globals.css"                     // SECOND

What Claude Will Do

  • Replace UI primitives (buttons, cards, inputs) with design system components
  • Use semantic color tokens like text-foreground and bg-background
  • Preserve existing page structure, layouts, and routing
  • Work incrementally - one component type at a time

What Claude Won't Do

  • Change page layouts, routing, or component hierarchy
  • Remove or reorganize page sections
  • Delete code assuming it's unused
  • Override design system CSS variables

You don't need to migrate everything at once. The design system components can coexist with existing code.

Troubleshooting

Unstyled components / CSS variables undefined

  • Verify @sourceful-energy/ui/styles.css is imported FIRST
  • Check package version is 0.1.22+: npm list @sourceful-energy/ui

Dark mode not working

  • Add suppressHydrationWarning to the <html> tag
  • Wrap app in ThemeProvider with attribute="class"

View the template: CLAUDE.project-template.md on GitHub