@ducksauce/presets-core

Design system tokens and Tailwind CSS preset for the Ducksauce design system. Provides consistent theming, spacing, typography, and color tokens across all applications.

🚀 Quick Start

Installation

npm install @ducksauce/presets-core
# or
yarn add @ducksauce/presets-core
# or
pnpm add @ducksauce/presets-core

Usage

import { tokens, themes } from "@ducksauce/presets-core";
import { ducksaucePreset } from "@ducksauce/presets-core/tailwind";

// Use in Tailwind config
export default {
  presets: [ducksaucePreset],
  // ... rest of config
};

🎨 Design Tokens

Colors

import { tokens } from "@ducksauce/presets-core";

// CSS Variables
tokens.colors.bg; // "var(--ds-bg)"
tokens.colors.fg; // "var(--ds-fg)"
tokens.colors.muted; // "var(--ds-muted)"
tokens.colors.accent; // "var(--ds-accent)"
tokens.colors.ring; // "var(--ds-ring)"
tokens.colors.border; // "var(--ds-border)"
tokens.colors.input; // "var(--ds-input)"

Spacing

tokens.spacing.radius; // "var(--ds-radius)"
tokens.spacing["radius-sm"]; // "var(--ds-radius-sm)"
tokens.spacing["radius-lg"]; // "var(--ds-radius-lg)"

Typography

tokens.typography["font-sans"]; // "var(--ds-font-sans)"
tokens.typography["font-mono"]; // "var(--ds-font-mono)"

Shadows

tokens.shadows.shadow; // "var(--ds-shadow)"
tokens.shadows["shadow-lg"]; // "var(--ds-shadow-lg)"

🌓 Themes

Available Themes

import { themes } from "@ducksauce/presets-core";

// Dark theme (default)
themes.dark = {
  bg: "#0b0b0c",
  fg: "#fff",
  muted: "#9aa0a6",
  accent: "#6ee7b7",
  ring: "#93c5fd",
  border: "#374151",
  input: "#1f2937",
};

// Light theme
themes.light = {
  bg: "#ffffff",
  fg: "#111827",
  muted: "#6b7280",
  accent: "#059669",
  ring: "#3b82f6",
  border: "#d1d5db",
  input: "#f9fafb",
};

Theme Type

import type { Theme } from "@ducksauce/presets-core";

const theme: Theme = "dark"; // or 'light'

🎨 Tailwind Preset

Basic Usage

// tailwind.config.js
import { ducksaucePreset } from "@ducksauce/presets-core/tailwind";

export default {
  presets: [ducksaucePreset],
  content: ["./src/**/*.{js,ts,jsx,tsx}"],
};

Extended Configuration

// tailwind.config.js
import { ducksaucePreset } from "@ducksauce/presets-core/tailwind";

export default {
  presets: [ducksaucePreset],
  content: ["./src/**/*.{js,ts,jsx,tsx}"],
  theme: {
    extend: {
      // Your custom extensions
      colors: {
        brand: {
          50: "#fef7ee",
          500: "#ff5a1f",
          900: "#7c2d12",
        },
      },
    },
  },
};

Available Classes

The preset provides the following Tailwind classes:

Colors

• bg-ds-bg - Background color
• text-ds-fg - Foreground color
• text-ds-muted - Muted text color
• bg-ds-accent - Accent background
• border-ds-border - Border color
• bg-ds-input - Input background

Border Radius

• rounded-ds - Default border radius
• rounded-ds-sm - Small border radius
• rounded-ds-lg - Large border radius

Fonts

• font-sans - Sans-serif font stack
• font-mono - Monospace font stack

Shadows

• shadow-ds - Default shadow
• shadow-ds-lg - Large shadow

🛠️ Development

Prerequisites

• Node.js 18.20.2 or >=20.9.0
• pnpm 10.13.1+

Setup

# Install dependencies
pnpm install

# Start development mode
pnpm dev

# Build for production
pnpm build

# Run linting
pnpm lint

# Clean build artifacts
pnpm clean

Project Structure

packages/presets-core/
├── src/
│   ├── index.ts           # Main exports (tokens, themes)
│   └── tailwind.ts        # Tailwind preset
├── package.json
├── tsconfig.json
└── README.md

Adding New Tokens

1. Add token to src/index.ts
2. Update TypeScript types
3. Add to Tailwind preset if needed
4. Update this README

Example Token Addition

// src/index.ts
export const tokens = {
  colors: {
    // ... existing colors
    success: "var(--ds-success)",
    warning: "var(--ds-warning)",
    error: "var(--ds-error)",
  },
  // ... rest of tokens
};

export const themes = {
  dark: {
    // ... existing colors
    success: "#10b981",
    warning: "#f59e0b",
    error: "#ef4444",
  },
  light: {
    // ... existing colors
    success: "#059669",
    warning: "#d97706",
    error: "#dc2626",
  },
};

📦 Building

Development Build

pnpm dev

This starts tsup in watch mode, rebuilding on file changes.

Production Build

pnpm build

This creates:

• dist/index.js - Main exports
• dist/index.d.ts - TypeScript declarations
• dist/tailwind.js - Tailwind preset
• dist/tailwind.d.ts - Tailwind preset types

Build Configuration

The package uses tsup for building:

{
  "build": "tsup src/index.ts src/tailwind.ts --dts --format esm"
}

🧪 Testing

# Run tests
pnpm test

# Run tests in watch mode
pnpm test --watch

# Run tests with coverage
pnpm test --coverage

📦 Publishing

Versioning

This package uses Changesets for versioning:

1. Create a changeset: pnpm changeset
2. Version the package: pnpm release
3. Publish: pnpm release (includes publishing)

Manual Publishing

# Build the package
pnpm build

# Publish to npm
pnpm publish

Package Configuration

{
  "name": "@ducksauce/presets-core",
  "version": "0.0.0",
  "type": "module",
  "main": "dist/index.js",
  "module": "dist/index.js",
  "types": "dist/index.d.ts",
  "sideEffects": false,
  "files": ["dist"],
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    },
    "./tailwind": {
      "types": "./dist/tailwind.d.ts",
      "import": "./dist/tailwind.js"
    }
  }
}

🔗 Dependencies

Peer Dependencies

• tailwindcss ^3.0.0

Dev Dependencies

• @types/node - Node.js TypeScript types
• eslint - Code linting
• tsup - TypeScript bundler
• typescript - TypeScript compiler

📚 API Reference

tokens

Design system tokens object with CSS variable references.

Properties

• colors - Color tokens
• spacing - Spacing tokens
• typography - Typography tokens
• shadows - Shadow tokens

themes

Theme color values for light and dark modes.

Properties

• dark - Dark theme colors
• light - Light theme colors

Theme

TypeScript type for theme names.

type Theme = "light" | "dark";

ducksaucePreset

Tailwind CSS preset configuration.

Usage

import { ducksaucePreset } from "@ducksauce/presets-core/tailwind";

export default {
  presets: [ducksaucePreset],
  // ... rest of config
};

🎨 CSS Variables

The design system uses CSS variables that should be defined in your application:

:root {
  /* Colors */
  --ds-bg: #0b0b0c;
  --ds-fg: #fff;
  --ds-muted: #9aa0a6;
  --ds-accent: #6ee7b7;
  --ds-ring: #93c5fd;
  --ds-border: #374151;
  --ds-input: #1f2937;

  /* Spacing */
  --ds-radius: 1rem;
  --ds-radius-sm: 0.5rem;
  --ds-radius-lg: 1.5rem;

  /* Typography */
  --ds-font-sans: ui-sans-serif, system-ui, sans-serif;
  --ds-font-mono:
    ui-monospace, SFMono-Regular, "SF Mono", Consolas, "Liberation Mono", Menlo,
    monospace;

  /* Shadows */
  --ds-shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);
  --ds-shadow-lg:
    0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
}

/* Light theme */
.light {
  --ds-bg: #ffffff;
  --ds-fg: #111827;
  --ds-muted: #6b7280;
  --ds-accent: #059669;
  --ds-ring: #3b82f6;
  --ds-border: #d1d5db;
  --ds-input: #f9fafb;
}

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Create a changeset
6. Submit a pull request

📄 License

This package is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Documentation: This README
• Issues: Create an issue in the repository
• Discussions: Use GitHub Discussions for questions

Built with ❤️ using Tailwind CSS and TypeScript.