Customization

Overview

PimentCSS is customizable at three levels, often combined:

• Sass @use … with (), typography, spacing, radii, semantic aliases ($surface-action, $text-body, …).
• Partial Sass entry points, pimentcss-design-system/core (tokens + layout + utilities) and pimentcss-design-system/components (UI).
• Canonical CSS tokens, edit tokens/colors.css (OKLCH palettes) and regenerate build artifacts.

All Sass knobs live in scss/abstracts/_variables.scss with the !default flag, so you override only what you need.

Prerequisites

• Sass ^1.69, npm install -D sass in your app (or use the CLI: npx sass).
• Installed package, pimentcss-design-system in node_modules (see Installation).
• Licensed fonts (optional), place Zodiak + Plus Jakarta Sans in fonts/, run npm run build:fonts (see fonts/README.md in the repo).
• Palette pipeline, only if you change tokens/colors.css: run scripts from the PimentCSS repo or copy updated styles/palettes.css.

Custom theme with Sass

Create a single entry file (for example src/styles/theme.scss) and pass overrides to the main bundle.

// src/styles/theme.scss
@use "pimentcss-design-system" with (
  $prefix: hm,
  $font-family-heading: "Zodiak", Georgia, serif,
  $font-family-body: "Plus Jakarta Sans", system-ui, sans-serif,
  $btn-min-height: 2.75rem,
  $border-radius-8: 0.5rem,
  $surface-action: #0f766e,
  $surface-action-hover: #0c5f59,
  $text-action: #0c5f59,
);

Import the compiled CSS once in your app (bundler or <link> after build).

// main.ts (Vite, webpack, …)
import "./styles/theme.css";

Compile your theme

From your project root, compile the Sass entry to CSS. Watch mode is handy while tuning tokens.

npx sass src/styles/theme.scss src/styles/theme.css

npx sass src/styles/theme.scss src/styles/theme.css --watch

npm run build:css

Add a script in your package.json: "build:css": "sass src/styles/theme.scss src/styles/theme.css --style=compressed".

Partial imports

Ship a smaller CSS bundle when you only need foundations or only components (components expect core tokens to exist).

// lean.scss, foundations only
@use "pimentcss-design-system/core";

// full-ui.scss, tokens + components
@use "pimentcss-design-system/core";
@use "pimentcss-design-system/components";

OKLCH color tokens

Reference palettes are defined in tokens/colors.css (Caribbean / Antilles hues). Semantic surfaces and text map through tokens/semantic.css.

1. 01

   Edit palette source

   Adjust OKLCH steps (--primary-*, --accent-*, …) in tokens/colors.css. Keep contrast in mind for light and dark semantics.

   colors.css

   /* tokens/colors.css */
   :root {
     --primary-600: oklch(48% 0.13 195);
     /* … */
   }

2. 02

   Regenerate artifacts

   From the PimentCSS repository (or a fork), refresh generated files and the published CSS.

   Terminal

   npm run generate:palettes
   npm run build:css

3. 03

   Use in your app

   Either depend on a new pimentcss-design-system release, or copy dist/pimentcss.min.css / token files into your pipeline.

   app.css

   import "pimentcss-design-system/tokens/colors.css";
   /* or link/dist copy after build */

Preview swatches on the Colors page after rebuild. The doc site loads palettes.css for preview classes.

Semantic tokens (light / dark)

Components consume semantic variables (--surface-page, --text-body, --border-default), not raw palette steps. Defaults live in tokens/semantic.css with [data-theme="dark"] and prefers-color-scheme overrides, tuned for RGAA / WCAG AA.

/* Optional: extend in your global CSS after pimentcss */
:root {
  --surface-page: var(--neutral-100);
}
[data-theme="dark"] {
  --surface-page: var(--neutral-900);
}

Prefix and feature flags

Rename the . namespace or toggle optional features at compile time.

@use "pimentcss-design-system" with (
  $prefix: app,              // .app-btn, .app-container, …
  $enable-local-fonts: true,
  $enable-google-fonts: false,
  $enable-fontshare-fonts: false,
  $enable-dark-theme: true,
  $enable-hex-fallback: true,
);

Light and dark mode

Set an explicit mode on the document root, or let the system preference apply when no attribute is set.

Add Theme toggle (.theme-toggle) in your header, or sync data-theme with your router / storage. See docs-site/src/lib/theme.ts in the repo for a minimal reference implementation.

Customize from a PimentCSS clone

Contributors working inside this repository can iterate without publishing to npm.

// scss/custom.example.scss (local)
@use "./pimentcss" with (
  $font-family-heading: "Zodiak", Georgia, serif,
  $surface-action: #0f766e,
);

// npm run build:css   → dist/pimentcss.css
// npm run docs        → docs-site with hot reload

Next steps