Skip to content
taureanPublic

About

A starter set of CSS files for building modular web components and layouts.

Topics

Resources

Stars

4 stars

Watchers

1 watching

Forks

Repository files navigation

suede-css

NPM Version GitHub commit activity GitHub Repo stars

A framework-agnostic CSS foundation: design tokens, sensible HTML defaults, layout primitives, and a deliberately tiny utility set.

Installation

pnpm (recommended):

pnpm add @taurean/suede-css

Direct download: Download suede.min.css in dist/.

Usage

Import globally once in your project as one of the earliest CSS files. This ensures design tokens and utility classes are available throughout your project.

@import '@taurean/suede-css';

Important: Only import once to avoid duplicate styles and ensure proper cascade order.

What's Included

  • Color system — OKLCH primitives (23 hues × 11 steps) plus semantic surface/text roles with automatic light/dark via light-dark() and a data-theme toggle hook
  • Fluid typography — responsive type scale, line heights, font stacks, weight tokens
  • Fluid spacing — responsive spacing scale using clamp()
  • Radii, borders, shadows, z-index, motion — token families for real UI work (dialogs, popovers, toasts), with prefers-reduced-motion handled at the token level
  • Accessibility baseline — global :focus-visible ring, u:visually-hidden, box-sizing reset, form inheritance normalization
  • CSS Grid layout — 12-column grid with responsive gutters
  • Layout primitives — l:waterfall, l:river, l:repel, l:root, l:grid, l:ui-list
  • Sensible defaults — base styles for HTML elements

Built from best practices and resources including Evil Martians' Harmony color palette, Cube CSS methodology, and Utopia fluid scales.

Overriding suede-css (cascade layers)

suede-css declares paired cascade layers:

@layer webfont, suede-token, token, suede-default, default, suede-utility, utility, suede-layout, layout;

Library styles live only in the suede-* layers. The bare layers (token, default, utility, layout) come later in the order and are reserved for you — anything you declare there overrides suede-css without specificity fights or !important. Unlayered CSS (e.g. component styles) overrides everything.

/* your stylesheet */
@layer token {
    :root {
        --fw-heading: var(--fw-bold); /* opt into bold headings */
        --hue-link: light-dark(var(--hue-violet-700), var(--hue-violet-300));
    }
}

@layer default {
    h1 { letter-spacing: -0.02em; }
}

Dark mode follows the OS by default; force it with data-theme="dark" (or "light") on <html>. On a subtree, data-theme switches the tokens inside it; the themed element paints its own background and text color with the surface tokens (e.g. --hue-z1-bg / --hue-z1-fg).

Claude Code users: this repo ships a skill at .claude/skills/suede/ for writing styles with suede-css — token catalog, override recipes, and conventions. Copy it into a consuming project's .claude/skills/.

Contributing to suede-css + publishing changes

Once changes are merged into main, run one of the release scripts (pnpm release:patch, pnpm release:minor, or pnpm release:major) to lint, check docs sync, minify CSS, update the package.json version, and publish to NPM.

  • pnpm build — update the minified CSS in dist/, useful for testing output before publishing
  • pnpm build:preview — write a non-minified CSS file to dist-preview/ (gitignored) for human-readable diffs
  • pnpm lint — stylelint over the source (catches invalid values and undefined var() references)
  • pnpm check:skill — verify the skill's token catalog matches the source
  • pnpm dev — live reload via browsersync to test the example HTML files while making style changes (files in examples/ rely on suede-css's global styles and classes; primitives.html adds a <style> block of component recipes built only from suede-css tokens)
  • Release scripts assume the GitHub remote is named origin

About

A starter set of CSS files for building modular web components and layouts.

Topics

Resources

Stars

4 stars

Watchers

1 watching

Forks

Used by

Contributors

Languages