@schandlergarcia/sf-web-components

Reusable Salesforce web components library with Tailwind CSS v4 and shadcn/ui components.

Installation

npm install @schandlergarcia/sf-web-components

Peer Dependencies

This package requires:

• React 18+ or 19+
• Tailwind CSS v4
• @tailwindcss/vite

Usage

Import Components

// Library components (for command centers/dashboards)
import { UIButton, MetricCard } from '@/components/library';
import { cn } from '@/lib/utils';

function Dashboard() {
  return (
    <MetricCard
      title="Total Sales"
      value="$1.2M"
      trend={{ value: 12, direction: 'up' }}
      footer={<UIButton variant="primary">View Details</UIButton>}
    />
  );
}

Note: After installation, components are copied to src/components/library/ for Tailwind scanning. Import from @/components/library (not from the package directly).

Import Styles

Add to your main CSS file:

@import '@schandlergarcia/sf-web-components/styles';

Tailwind Configuration

Extend your tailwind.config.ts:

import type { Config } from 'tailwindcss';

export default {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@schandlergarcia/sf-web-components/dist/**/*.{js,jsx}'
  ],
  theme: {
    extend: {}
  }
} satisfies Config;

Components

This library includes:

• UI components (Button, Card, Input, etc.)
• Data components (Tables, Lists)
• Chart components (via Recharts)
• Form components
• Filter components
• Layout components

Sample Data

The package includes pre-seeded sample data in the data/ directory:

• Engine Travel Command Center sample data with real Salesforce field names
• Dashboard-ready data (map markers, chart data, metrics, etc.)
• Easy to swap for live data later

Copy to your project:

# From your webapp directory
cp node_modules/@schandlergarcia/sf-web-components/data/engine-sample-data.js src/data/

See data/README.md and data/USAGE.md in the package for full documentation.

Utilities

import { cn } from '@schandlergarcia/sf-web-components/lib';

// Merge Tailwind classes with conflict resolution
const className = cn('px-2 py-1', 'px-4'); // Result: 'py-1 px-4'

Development

# Install dependencies
npm install

# Build the library
npm run build

# Build types only
npm run build:types

Contributing

⚠️ IMPORTANT: Read CONTRIBUTING.md before making changes.

Key Rules

• Component names MUST match .a4drules/skills/component-library/ documentation
• Library components use UI prefix (UIButton, UIInput) - NOT shadcn names
• Update CHANGELOG.md with EVERY change before publishing
• Run verification scripts before committing

Quick Checks

# Verify consistency between code, docs, and templates
npm run verify

# Pre-publish verification (runs automatically before publish)
npm run prepublish:check

Documentation Structure

• ARCHITECTURE.md - Source of truth hierarchy
• CONTRIBUTING.md - Contribution guidelines and checklists
• CHANGELOG.md - Detailed version history
• .a4drules/RULES.md - Mandatory project rules

Publishing

This package publishes to the public npm registry at https://registry.npmjs.org.

Prerequisites

• Be logged in to npm: npm login
• Have publish permissions for the @schandlergarcia scope

Publish Process

The prepublishOnly script automatically runs verification checks.

# 1. Update CHANGELOG.md with your changes
#    Add entry under ## [X.X.X] - YYYY-MM-DD

# 2. Bump version
npm version patch  # 1.9.43 → 1.9.44
npm version minor  # 1.9.43 → 1.10.0
npm version major  # 1.9.43 → 2.0.0

# 3. Publish (verification runs automatically)
npm publish

The prepublishOnly hook will:

1. Run consistency verification (npm run verify)
2. Check CHANGELOG has entry for current version
3. Verify UIButton.tsx and UIInput.tsx exist
4. Build the package
5. Block publish if any checks fail

Manual Verification (Optional)

# Run all pre-publish checks manually
npm run prepublish:check

# Run only consistency checks
npm run verify

If Publish Fails

If verification fails:

1. Read the error output carefully
2. Fix the reported issues
3. See CONTRIBUTING.md for detailed guidance
4. See .a4drules/RULES.md for rules
5. Run npm run verify to check fixes
6. Try publishing again

The package is published as public and can be installed by anyone:

npm install @schandlergarcia/sf-web-components

🤖 AI Agent Skills

This package includes Claude Code agent skills that teach AI how to work with these components.

The .a4drules/ directory contains:

• Skills: Step-by-step guides for building with this library
• Features: Feature-specific implementation rules
• Docs: Data access patterns and UI conventions

Using with Claude Code

When you install this package, Claude Code automatically discovers the skills and uses them to:

• Build components correctly
• Follow your architectural patterns
• Use the right data access methods
• Apply consistent styling

Available Skills

Check .a4drules/skills/ for the full list of included agent skills.

License

MIT